I tend to write what I call "immature" code, in that I don't go for all the fancy syntax, nifty "tricks" that just mean the same thing in less lines of code, etc. I find that this is a good thing rather than a bad thing. Generally when I see that type of coding practice, although I can understand it, it tends to detract from the flow and clarity of the meaning. I guess it's like spoken language: you can speak the jive, but unless you speak it, it's not always clear.

That's not to say that I can write that code like that: I can. Maybe it detracts from the flow just because I don't write that way. Just like spoken language.

Spoken language is about communication: the transfer of information between people. The information is the important part, not the longest words that you can use. Same with coding: what it does is more important than how obscure it is. (Of course, I assume no difference in efficiency, etc, but that's another story).

The important distinction here is to specify who we're communicating with when we write code. First we're communicating instructions to a compiler. The compiler doesn't care how tricky or obscure we are, just as long as the syntax is correct. So why am I rambling on? Because we're also communicating with the next person who comes along and has to read this code, typically the maintainer. This may or may not be the same person that wrote the original code: we generally don't know, except to say in industry they typically aren't. That said, making assumptions about the level of comprehension that the maintainer has is a Bad Thing(tm). Therefore, writing code in a manner that enhances readability and clarity makes the next persons job easier.

Some would argue that this is the purpose of block header and inline documentation. Somewhat it is, however documentation of this nature tends to be repetitive. In general, I believe that block header documentation should be an overall description about the purpose of the code (including the interface specification, if applicable), possibly outlining the approach taken to achieve that. Inline documentation should serve a similar purpose: to clarify the impact of certain operations and how they influence the result, if that may have the potential to be unclear. Again, this is to aid comprehension of the code.

You never know, that next person reading that code might be you.