Coding Guidelines: Finding the Art in the Science

Hi, you are not taking your twitter communication serious, are you?

The article is extremely inconsistent with regard to the examples.
The guidelines described here are NOT applied to the examples.

A very good example is Fig. 13: http://deliveryimages.acm.org/10.1145/2050000/2043191/figs/f13.jpg

I hope it is just a technical problem like tabs vs. spaces and an editing process that is not used to handling source code.

Please consider fixing this article, it is just embarrassing.

Thanks!

Thanks for the comments and reading of the paper! There are some errors in the examples, and we appreciate you bringing this to our attention. We will see if we can get them corrected.

--Robert C. Green

The errors in the figures were very distracting, e.g., Fig. 1 was a disaster:
-- several duplicate case labels
-- "case default" is invalid syntax
-- System.out.printIn is not defined
Whoever wrote this gets an "F".
All writers in Communications should compile their examples before submitting -- it's an old rule that still holds.

Thanks for your article!

I would have liked to see how this relates to Knuth's Literate Programming... Any ideas on that?

While I’m not very familiar with literate programming, I believe there is definitely some overlap with what we have presented. For example, consider this excerpt from Knuth’s “Literate Programming”:

"The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible…"

This is a statement that could have easily been included in this paper and clearly works well with what we have presented. This is particularly true regarding the guideline “Let Simple English be Your Guide”.

One difference appears to be our guideline of “Focus on the Code, Not the Comments.” Literate programming seems to be focused deeply on comments and documentation instead of letting the code speak for itself through its design.

Again, this is a cursory comparison and it would be interesting to perform a deeper and more through comparison with our guidelines.

-Rob Green

Thanks a lot for your inspiring article. Every developer should strive for better code quality and readable variable/class/method names. My gold standard when it comes to code quality is "Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin)". There are a number of differences to your suggestions, for example Robert C. Martin does not recommend the horizontal alignment of code, because he thinks the real problem is the length of the lists - and I agree with that, although I used to align my code for years (it's still useful with certain programming languages or assembler code, when you can't avoid long lists).