Articulate Coding | Hacker News Reader

Articulate Coding

casestatement.tumblr.com

77 pointscasenelson26 comments

OP is unintentionally superficial, but he's grasping at a greater understanding and he knows. I think this is what he is looking for:

Why is this idea true?

Do I really believe it?

Could I convince someone else that it is true?

Why didn't the author use a different argument?

Do I have a better argument or method of explaining the idea?

Why didn't the author explain it the way that I understand it?

Is my way wrong?

Do I really get the idea?

Am I missing some subtlety?

Did this author miss a subtlety?

If I can't understand the point, perhaps I can understand a similar but simpler idea?

Which simpler idea?

Is it really necessary to understand this idea?

Can I accept this point without understanding the details of why it is true?

Will my understanding of the whole story suffer from not understanding why the point is true?

-- How To Read Mathematics, authors Shai Simonson and Fernando Gouvea [1]

[1]http://web.stonehill.edu/compsci/History_Math/math-read.htm#

These 12 points seem to be the most insignificant things you can think about your code. Indentation? Camel case? Come on... mastering WRITING code will not make you a good coder. It will make your code consistent, I'll concede, but there's nothing stopping your from writing consistently bad code that looks good. Wouldn't it be more fruitful to think things like: 1) Why did I write this code as one function? 2) Should I not write this query in a loop? 3) How much memory will this array take to store? 4) Will I understand this code 3 months from now? 5) Is this code readable without comments 6) Would commenting this block help the reader understand my intentions? 7) Should this be a class, and if so, how complex will it be? 8) Can I make this code reusable?

The two go hand-in-hand. Writing articulate easy-to-read code does not mean it precludes thinking about the things you mention. You could be the best (according to your criteria) coder in the world, but if your code is unreadable, it will quite literally waste others' time. This might not seem like a big deal with a smaller project, but scale to something the size of the Linux kernel or larger and it begins to become an issue.

http://www.kernel.org/doc/Documentation/CodingStyle

I've rarely seen such poor code visually that it made it hard to follow - except in the rare case where someone commits line breaks incorrectly. Camel-case, underscores, indentation etc.. do not vary so widely as to prevent me from understanding code. What does prevent me from understanding code is 5-10 nested if blocks and insane logic checks without commenting.

Have you actually experienced a coder that writes good code but writes it in a manner that prevents you from understanding it? I'd love to see some actual code samples.

> What does prevent me from understanding code is 5-10 nested if blocks and insane logic checks without commenting.

What's worse is multiple nested levels of #ifdef. Not only is it hard to tell how the code flows, but you can't even be sure it's all being compiled!

I work with code like this so frequently that I actually got around to learning elisp so that I could write a function in Emacs to highlight the nested levels of #ifdef. I have a black background, so each nested level increases the brightness.

(I should really get around to pulling that code off of my computer at work and putting it up for everyone to use...)

That code sounds pretty interesting, especially if it's adaptable to arbitrary open/close sequences

    if (.*?) {

    #ifdef .* ... #else ... #endif

I'd be interested in seeing it, even if it's a pastebin/gist dump that needs some cleanup.

Unfortunately, it's only for #if .* ... #el.* ... #endif. I didn't want to write that much of a parser, so I just push the line number onto a stack if I see a line like /^\s*#if/.

I guess Emacs is using some kind of parser to do syntax highlighting, right? I wonder if it's possible to tap into that...

Yeah, I'm pretty sure it does, although I've never poked deeply enough / understood elisp well enough to know exactly how it does it.

Swapping out those regexen you have wouldn't be too much of a challenge, I don't think, at least for a first shot at it.

I'm more interested in the general structure of managing the counter, applying the various faces to lines, etc.

My email is in profile if you want someone to attempt to clean it up a bit (insofar as I'm capable of doing so) :)

as long as the code isn't deliberately formatted poorly, i don't care, not even a bit. besides our codebase we have a large set of dependencies, and we read and maintain dependencies all the time. whether their coding style is consistent with mine is irrelevant, I slog through it and stfu and get my job done.

This is a great comment. I worried that my example was too simplistic, it's difficult to bring up design decisions (as opposed to coding style decisions) without context. For many of my questions, you'll write them down, understand them and move on to deeper questions. However, they weren't all about consistency. I think naming is particularly important, drives design, and is often overlooked.

But the exercise shouldn't stop there, as your program develops questions like yours should be asked and understood and defined. The more questions you can ask yourself, the better you'll understand your thought process.

New developers might not get far past my list. Most devs might ask some but not all of your questions. The best developers will realize more fundamental questions to ask about their decisions. Hopefully everyone can learn something new by asking those questions.

I understand the point of the exercise and I can see that an individual coder might gain some benefit from this.

However, in a professional environment you would expect that the lead developer(s) had already given this stuff a lot of serious thought and enshrined it in a coding standards document for every member of the team to follow.

I have a copy of Code Complete on my desk, it is 915 pages long. The techniques in there have been gathered from years of experience and research. There's no way I'll ever absorb all of the knowledge in there, but some of it may stick. When I write code I might unconsciously pick out a technique from the book, yet later on I'll miss the opportunity to apply the same technique again. If I better understood what I was doing the first time, I'd be more aware of it later.

Now, you're right, the easiest questions (as in the article) to answer can and should be encoded in standards document. But there are many many questions to ask and some are highly dependent on context and don't belong in standards documents. Maybe some of the existing standards that you thought you understood are really just there by convention and could be improved.

A good idea is to check for certain style issues which you want to enforce and are easy to catch at checkin time. You can enforce things like no real tabs, line width, no trailing spaces, etc and make the person checking in the code get rid of it. Usually once it winds up in VCS[1], it is harder to go back and clean it up. People make mistakes all the time, and tools are scriptable.

[1] Or do it at merge time if your setup involves pushing to a "work" repo which is merged to the real codebase later.

I'd argue that if it's so easy to check you can do so with a commit hook, you should also automate fixing it. If you're using C, C++, C#, or Java, you can do this with astyle pretty easily, for instance.

As a novice programmer, I found this article to be a good bump towards thinking for myself. Too often I find myself doing something because its what the tutorial or book I was reading said was best practice, without really thinking the situation through. Being able to explain why you are making the decisions that you make seems like an important step between just haphazardly piecing together snippets of code you memorized and actually logically solving problems.

Hooray! That's a big step toward becoming a better programer. (I've worked with programmers with years of experience that still just slap code together.) Your comment also painted the article in a new light for me. Perhaps doing this level of documentation would make a good exercise for newer coders. Maybe on a smaller scale - document every token in this method, or similar. I'm going to figure our a way try this now, thanks. :)

I think that individual code design culture comes from trying many languages and different use cases, picking up the best practices on the way. I remember using Pascal and then acknowledging that "begin" and "end" are better expressed with curly braces in C. When using Delphi I learnt a lot of OOP principles so I could later easily pickup Java and took some good habits from there also, later came PHP where I started noticing vertical readability is important, so when I saw Python I was stunned. Functional programming hit me, but not so hard, because I used AutoCAD LISP years ago and it felt natural. Trough the years I started to notice new things I would need in my daily coding and I found nirvana when I saw Ruby.

After years of coding one develops their coding personality that they're happy with and I think their code has just a right mix of carelessness and precision which could be never learned from a script kiddie book.

Interesting. But from the heading I thought this was going to be about something else. Articulate coding could mean 'using bigger words' in the sense that you'd refactor your code and use built-in functions wherever possible.

Point being that most people probably don't get the most out of, say, Python's standard library.

For me, the answer to most of those questions is "it's in the company's style guide". No thinking required, no thinking allowed!

Sometimes I find myself doing this in a small way right after I deploy a new product version or feature. My mind is open enough to take in some of the decisions that were made to get to that point.

Also known as analysis paralysis.

I do not think that term means what you think it means.[1][2]

This isn't what I understand to be Analysis Paralysis. AP is when you're trying to analyse the problem and design you're trying to code, and you're overwhelmed by the decisions to make and as a result, unable to proceed.

This, in contrast, is about deliberate reflection on what you're doing so you can better make explicit all the otherwise implicit and internal decisions of which you may otherwise be unaware.

As the article says, coders make hundreds of decisions for every routine they write, most on auto-pilot. Some of those might be less than optimal, and this kind of examination and reflection can help to understand, and possibly improve, those decisions.

[1] Minor edit in the light of subsequent comments.

[2] Hat tip to The Princess Bride

I got the impression that icandoitbetter was being snide.

Agreed, but some of these questions-- the ones about indent style in particular-- don't seem to me to be the kind of things a developer needs to be thinking about while they're working on getting code written. The endless bickering and bikeshedding that arguments over coding conventions always result in are one thing, but having these arguments with yourself, every time you write a line of code, is crazy!

But the point was exactly not to be making these decisions consciously every time you write code. The point - in agreement with you - was that these decisions are not necessarily important.

The argument is that these decisions are made, whether you are aware of them or not, and in this case Beck was undertaking to understand them in nit-picking detail so they can be made visible and better understood, rather than remaining implicit, ill-understood, and possibly sub-optimal.

The author wasn't advocating that this sort of thing be done of every line of code - that would be ludicrous in the extreme. Don't attack the extreme strawman, try to understand and appreciate the underlying purpose.

In my 35 years of software work, far, far too often I see people concentrating on the pointless - bike-shedding if you will - and sadly, this is another case. Concentrate on the point that matters - understanding the processes and decisions of coding, and not the details of the specific instance.

In my 35 years of software work, far, far too often I see people concentrating on the pointless

The pointless has one great advantage: it is easier to work with. Hard problems are The Unknown, we fear the unknown, and when this fear arises one way to resolve it is by replacing the hard problem with something easier. This is absurd, like the drunk looking for his car keys under the street lamp on the wrong side of the street "because the light's better here", but that doesn't stop us, it just means we do it unconsciously. Now we have a simpler problem that we can concentrate on and (best of all) argue about.

You see this in obvious places like curly brace wars, but there are more interesting examples, such as why editors and version control systems get so much attention. They're important, but not that important. But they're easy to understand and have an opinion about. Better still, they're common across many projects so arguing about them is a way for programmers to socialize.

Perhaps the same pattern is behind our industry's tendency to embrace savior paradigms (Structured Programming, OO, Agile, FP).

Reply on news.ycombinator.com