Articulate Coding

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

by casenelson • 15 years ago

77 26 15 years ago

casestatement.tumblr.com

icandoitbetter• 15 years ago

Also known as analysis paralysis.

ColinWright2• 15 years ago

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

damncabbage• 15 years ago

I got the impression that icandoitbetter was being snide.

kenkeenan• 15 years ago

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!

tadruj• 15 years ago

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.

DillonF• 15 years ago

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• 15 years ago

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

Tycho• 15 years ago

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.

becomevocal• 15 years ago

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.

arctangent• 15 years ago

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.

apaprocki2• 15 years ago

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• 15 years ago

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.

casenelson2• 15 years ago

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.

methodin2• 15 years ago

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?

apaprocki2• 15 years ago

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

methodin2• 15 years ago

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.

dustingetz2• 15 years ago

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.

casenelson2• 15 years ago

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.

dustingetz2• 15 years ago

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#

resnamen• 15 years ago

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

Articulate Coding

Related Stories