I'm becoming increasingly convinced that good coding and good writing have a lot in common. Structure, clarity of names, use of comments all work together to tell a story on two levels: one to the machine that will compile it and one to the person reading or maintaining it.
If you write a paper for a scientific journal, magazine or a university course there are clear guidelines for formatting, footnote and citation style, length of abstract, and so forth. All of these are meant to speed up the reading and review process. None of these pretend to try to make the article into a better article.
I think we ask too much of coding standards. We want to them to create good code. They can't. Only clear thinking about the code and how to explain it to other readers down the line can. Comments, variable names, structure are all tools that can work together in this effort. Sometimes they are interchangable. Sometimes they are not. Trying to come up with fixed rules about how they should be used actually impedes the writing process rather than helping it.
When I started out leading teams I used to get very fussy about how people coded. I've grown up since then and have moved more to a minimal set of standards focused entirely on readability and error detection. I try to focus on those that make it easier to skim code and leave the quality of code issues to other parts of the team process (e.g. code reviews). These are some of the standards that have worked for me and my teams (YMMV):
- Standard organization. If one file places public methods at the top and another at the bottom it is hard to skim through a large number of files. It really helps to know where to look for things in a file.
- Standard abbreviations. We have a list of standard abbreviations for words that commonly show up as part of variable names. Long descriptive names are a pain, but if everyone makes up their own abbreviations, code becomes illegible and variable names cease to be self-documenting. For the list to be useful it has to be short. For less common abbreviations the rule of thumb is (a) choose one (b) be consistent (c) for any abbreviation that isn't obvious from context, add a note somewhere at the top of your file listing the abbreviations you use and what they mean.
- Standard indenting. Standard indenting makes code so much easier to read. It really doesn't matter how much you indent as long as you do it consistently so that you can reasonably expect that adjacent lines of code at the same indentation level will be executed in sequence.
- Consistency. Whatever style you choose, be consistent. People can read a file more quickly if they can assume a single consistent style through the file.
- An alpha "sigal". When the content of a scalar variable is not blindingly obvious (e.g. while ($line = <DATA>), we put a one or two letter content type indicator at the beginning of variable name, e.g. $aUserNames. This is not standard Perl style, but I have found it very helpful none the less. The goal isn't to exhaustively type variables. Rather, this is mainly to distinguish quickly between scalars holding strings, numbers, arrays, code references, regular expressions, hashes, and things that are intentionally multi-typed. There are usually several ways to represent "foo" - it may have a name, an id, a hash storing fields by name, or a record containing several fields in a particular order. By giving it a one or two letter prefix to indicate which of these you mean, you can set up a lot of expectations about how the variable should be used. This makes it easier to skim the code. It also focuses one's attention during careful reviews. We use "s" for string, so if one sees "$sFoo == $sBar" one knows to look more closely for a possible error - either a misnamed variable or a misused operator.
Anything else is up for discussion. Over time I've come to believe that things like cuddling vs. not-cuddling don't have a huge impact on readability, so long as one approach or the other is used consistently within a code sample. We can learn to read code either way and probably should. The items listed above seem to matter more because they reduce the time spent searching up and down a file to figure out what someone meant.
Best, beth
Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
Read Where should I post X? if you're not absolutely sure you're posting in the right place.
Please read these before you post! —
Posts may use any of the Perl Monks Approved HTML tags:
- a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
| |
For: |
|
Use: |
| & | | & |
| < | | < |
| > | | > |
| [ | | [ |
| ] | | ] |
Link using PerlMonks shortcuts! What shortcuts can I use for linking?
See Writeup Formatting Tips and other pages linked from there for more info.