81–90 of 198 posts
An official style guide? Maybe. But it is one of common philosophies. See for example:
"If you need to comment something to make it understandable it should probably be rewritten."
http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-...
Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on. Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years lat…
At any given time I'm writing code as clearly as I can given my experience and body of knowledge. It also is representative of my exposure to and familiarity with the problem domain at that point in time. As these things evolve, my older code ceases to be as clear as I thought. It may very well not be the way I'd solve the problem again.
And that's before I need to start making changes to code clarity to satisfy a hard requirement (reduce memory usage, cache values, tighten up performance, etc.).
Earlier quoted context omitted.
I wonder where the idea comes from that people that write code that's hard to understand, will write comments that are easy to understand.
Well, native language and programming languages aren't the same thing and you express yourself differently in them. That's basically a given. But comments are most useful when they explain why something is being done, not what's being done. The latter is usually simple to work out with even the most hideous code. But if I don't know what you were trying to do or why you did something in a particular way, seeing what…
There are times when you absolutely want to comment something like an "Add" or "Swap" function. eg. // The reason we use a custom swap function instead of // the one that is shipped with the framework is because // of an edge-case that occurs quite frequently in our // scenario // Refer to Change Request 345. void Swap (Foo a, Foo b) ....
I've always treated comments as code smells. Not necessarily something bad, but something that at least suggests the possibility of suboptimal code. One of the best cases for comments IMO is documenting an unexpected behaviour on the part of a third-party API. But even then, correct exception / error-handling code can obviate the need for comments in many cases. If I'm reading code (from an experienced programmer) an…
The situation must be differentiated by language/environment. The suggestions for Haskell are certainly not bad. They hold, too, for many systems programming. For scientific coding, comments should align with the underlying theory for the code: “This implements matrix transposition with regard to ... as defined by ...”, so that next generations can align code with papers better. And when you’re in a wacky environment…
100x this. Scientific software should be held to a different set of standards than non-scientific software, primarily because you can probably not assume that your reading is familiar with the underlying domain.
Earlier quoted context omitted.
> Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along. Whatever their benefits are, this is not true at all. Comments are expensive to write and maintain. They are VERY VERY expensive to maintain because there is no automated way to test them.
Forgive my ignorance, but why and how would you test a comment? They don't do anything, there is no instruction for the machine to understand or run.
Earlier quoted context omitted.
Well, native language and programming languages aren't the same thing and you express yourself differently in them. That's basically a given. But comments are most useful when they explain why something is being done, not what's being done. The latter is usually simple to work out with even the most hideous code. But if I don't know what you were trying to do or why you did something in a particular way, seeing what…
But all too often, people who write hideous code sprinkle it with comments that merely explain what is done, at the lowest level.
Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on. Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years lat…
I wonder where the idea comes from that people that write code that's hard to understand, will write comments that are easy to understand.
Leaving a note about that weird thing is probably a good idea.
Earlier quoted context omitted.
Forgive my ignorance, but why and how would you test a comment? They don't do anything, there is no instruction for the machine to understand or run.
Then you will read the comment that says to do one thing but the program will do a completely other thing. I don't see any problem, do you?
Comments are highly valuable but like any tool they can be abused, or done in such a way that they don't make things better.
swap :: (a, b) -> (b, a)
swap (x, y) = (y, x)
map :: (a -> b) -> [a] -> [b]
map f [] = []
map f (x:xs) = (f x):(map f xs)
On the other hand, at 10,000 lines of code, a lot of that being parochial business logic, I'm going to want high-level documentation of why all this code exists. My emotional impulse is going to be to throw out all this shit code (in the business world, all code is shit) so please tell me why that is a bad idea. (I know it is, and I'm not going to do it, but please tell me why I'm not going to do it.) I'm going to want an entry point. I can't count the number of days of life I've lost just looking for entry-points in gigantic enterprise codeballs. Like, what actually runs?
Actually, 10,000-line single-programs should be rare-- Big Software is almost always a mistake, see here: http://michaelochurch.wordpress.com/2012/04/13/java-shop-pol... but that's another rant.