

Articulate Coding - casenelson
http://casestatement.tumblr.com/post/11213857807/lunch-and-learn-articulate-coding

======
dustingetz
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#>

------
methodin
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?

~~~
apaprocki
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>

~~~
methodin
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.

~~~
rcfox
> 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...)

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

    
    
        if (.*?) { 

vs

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

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

~~~
rcfox
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...

~~~
shabble
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) :)

------
arctangent
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.

~~~
apaprocki
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.

~~~
pmiller2
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.

------
DillonF
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.

~~~
techdmn
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. :)

------
tadruj
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.

------
Tycho
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.

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

------
becomevocal
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.

------
icandoitbetter
Also known as analysis paralysis.

~~~
ColinWright
_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_

~~~
kenkeenan
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!

~~~
ColinWright
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.

~~~
gruseom
_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).

