For my it is just the opposite. I never understood the mantra of ‘writing comments’ is wrong because whatever.
Firstly, code never expresses intent, only actions. Extracting the intent from actions is not trivial, so comments add this knowledge to the codebase.
Comments are documentation and this is something mandatory in programming. I want documentation not only at function level, but at program organisation and structural level (modules), how the modules interact, how the compiling phase works, what input and output is needed to run the program, who should use the tool and how, what requirements it covers… well, I want to understand all of these without reading a line of code, specially if the program has more than 10k lines of code.
Also nobody programs for the compiler only (or the interpreter). In programming there are a lot of tasks that are necessary and are not coding. I don’t understand why nobody doubts we need to have version control tasks, compiling/release tasks, bug tracking tasks… but comment writing is not needed.
Personally if your dev. team is not keeping your code and comments/doc in sync… it’s time to discuss this with them or find a new team.
5 and 8 would seem to be at odds. Much of the fun I have programming comes from doing something and then seeing what happens. That holds for professional development too. Solving a new problem often requires some amount of exploratory programming. If you know what you’re doing before you do it, you’re missing an important part of “research and development”.
I’m not sure I can agree that 5 and 8 are at odds. And, to your point about exploratory programming, by definition, you haven’t defined the problem yet–you’re still thinking about it. When you’re done figuring out what you’re doing, then you write a spec (formal or informal, it doesn’t matter. Though a formal spec has the advantage that you can probably use a model checker of some sort to assert that what you’re saying makes some sense). After the spec, i.e. after you’ve thought about it, you still have a ton of problems that are fun. How do you translate that spec into something you can execute?
I’ve seen my fair share of exploratory programs which have a little more slapped on them and are tossed into production. It’s almost never a good idea, and leads to loads of problems down the road. We’re dealing with that right now and I definitely want to avoid it in the future.
In Thinking for Programmers, Lamport argues this case much better than I can. He also makes the point that TDD or Agile, or whatever the hell else you want to use to actually produce the code doesn’t matter. Just write a spec first.
Rule 5 didn’t allow for much exploratory programming in my reading. If we exclude exploratory programming from “programming”, then I suppose it works. I think “build one to throw it away” is often a good strategy. I hesitate to call it advice, though, because it’s not always applicable.
I think if you’re writing down “rules all programmers should live by”, rules which invite “torrent[s] of ‘comments’ in the comment section below” are probably not appropriate.
Rule 4 about comments was well argued.
For my it is just the opposite. I never understood the mantra of ‘writing comments’ is wrong because whatever.
Firstly, code never expresses intent, only actions. Extracting the intent from actions is not trivial, so comments add this knowledge to the codebase.
Comments are documentation and this is something mandatory in programming. I want documentation not only at function level, but at program organisation and structural level (modules), how the modules interact, how the compiling phase works, what input and output is needed to run the program, who should use the tool and how, what requirements it covers… well, I want to understand all of these without reading a line of code, specially if the program has more than 10k lines of code.
Also nobody programs for the compiler only (or the interpreter). In programming there are a lot of tasks that are necessary and are not coding. I don’t understand why nobody doubts we need to have version control tasks, compiling/release tasks, bug tracking tasks… but comment writing is not needed.
Personally if your dev. team is not keeping your code and comments/doc in sync… it’s time to discuss this with them or find a new team.
5 and 8 would seem to be at odds. Much of the fun I have programming comes from doing something and then seeing what happens. That holds for professional development too. Solving a new problem often requires some amount of exploratory programming. If you know what you’re doing before you do it, you’re missing an important part of “research and development”.
I’m not sure I can agree that 5 and 8 are at odds. And, to your point about exploratory programming, by definition, you haven’t defined the problem yet–you’re still thinking about it. When you’re done figuring out what you’re doing, then you write a spec (formal or informal, it doesn’t matter. Though a formal spec has the advantage that you can probably use a model checker of some sort to assert that what you’re saying makes some sense). After the spec, i.e. after you’ve thought about it, you still have a ton of problems that are fun. How do you translate that spec into something you can execute?
I’ve seen my fair share of exploratory programs which have a little more slapped on them and are tossed into production. It’s almost never a good idea, and leads to loads of problems down the road. We’re dealing with that right now and I definitely want to avoid it in the future.
In Thinking for Programmers, Lamport argues this case much better than I can. He also makes the point that TDD or Agile, or whatever the hell else you want to use to actually produce the code doesn’t matter. Just write a spec first.
Rule 5 didn’t allow for much exploratory programming in my reading. If we exclude exploratory programming from “programming”, then I suppose it works. I think “build one to throw it away” is often a good strategy. I hesitate to call it advice, though, because it’s not always applicable.
I think if you’re writing down “rules all programmers should live by”, rules which invite “torrent[s] of ‘comments’ in the comment section below” are probably not appropriate.