33 ms·

The counterargument is that code should be self-documenting. If code is complicated enough to need comments, refactor it. Behavior should be obvious from func

by T-hawk 13y ago

The counterargument is that code should be self-documenting. If code is complicated enough to need comments, refactor it. Behavior should be obvious from function and variable names. If you can't say what a method does in its name, it's too big. The best code transcends the need for comments. What you describe about the development process, to write down the thinking and edge cases and decisions and such, is important but doesn't really belong in the source code. That stuff belongs in your issue tracker system or the commit messages. What other medium tries to embed a description of the creative process in the work itself? Da Vinci didn't write on the back side of the Mona Lisa the production process for his paints. Tolkien didn't explain how he created the Elvish language in the text of the novels. There's accompanying material for that. But realistically for software, that accompanying material is not going to get read elsewhere, or survive long-term through migrations to different tools and hosts. So it ends up in the source as the only way to keep it with the code and visible ten years later. Commenting is a least-bad solution, not a good one. And of course, policies for code commenting never work. You just get scintillating gems like "x+=5; //add 5 to x".

robomartin 13y ago
> code should be self-documenting Which is a myth. Try to come back to code five years and three languages later and see how self-documenting it is. It isn't. I could maybe --possibly-- stretch disbelief and accept that if someone works with one language and one platform for a long time the code will be self documenting to that person or that team. This is not the case for multi-technology projects with generations of people touching the code base. I'll give you a very concrete example. About fifteen years ago we spent three months authoring a tool in Visual Basic for Applications (VBA). This tool was used to automate certain aspects of the EDA (electronics design software) tool we were using at the time. The custom software was needed in order to vastly improve productivity with 1,000+ pin chips. The VBA tool effectively linked Excel with PCAD and reduced a twelve hour task to less than an hour. Well, I have not touched VBA in probably fifteen years. The code is full of comments about the very things I described in my prior post: intent, design, thoughts, ideas, enhancements, problems, etc. After fifteen years of not touching the language or the application I can jump into that code base and be up and running within not much more than an hour. It is hard to place a number on the value this adds to a project. It is nothing less than huge when it comes to supporting, maintaining, migrating and enhancing it. > "x+=5; //add 5 to x" Clearly the domain of morons.
iloveponies 13y ago
The idea that code be "self-documenting" is naive at best. Action does not necessarily infer intention, and without explanation can lead to assumption. To reach the code we end up committing a process of thought should have occurred by those who wrote it. For some things such as "boilerplate" code this may not be seen as significant. For others of increased complexity like explaining interactions between two pieces of logic, performing a complex set of logic or the expected usage of an externally provided interface comments are in my opinion essential. In contrast to what you've said I completely disagree with the notion that the "best code transcends the need for comments". I'd argue the best type of code has the most effective comments in line with code to ensure the next person can gain with the least amount of effort clear understanding of both the rationale and of the functionality that lead to what they see before them.
crpatino 13y ago
> What you describe about the development process, ... , is important but doesn't really belong in the source code. Except that in really big/successful projects, the proper places are outdated specs that end up buried in obscure unindexed archives. This can happen for a lot of reasons, technical debt, intellectual property acquisition, erosion of institutional knowledge due to personnel attrition, etc. On the other hand, source code is forever. It is the thing that you cannot unknowingly get rid off without getting rid of (your ability to update) the product itself. > Da Vinci didn't write on the back side of the Mona Lisa the production process for his paints. If you were a curator of the Louvre Museum, your job would have been easier if he did.
davidcuddeback 13y ago
> The counterargument is that code should be self-documenting. If code is complicated enough to need comments, refactor it. Behavior should be obvious from function and variable names. If you can't say what a method does in its name, it's too big. The best code transcends the need for comments. I used to believe that too, but I now believe that that point-of-view only addresses the accidental complexities of reading code. Don't get me wrong, descriptive function and variable names are great and make understanding code much easier. But I think it misses the forest (program structure) for the trees (functions). Where I get off that train is when trying to understand a program's structure. How do the modules decompose the problem being solved? Why was it designed a certain way? There's usually a combination of technical and domain knowledge that influenced the design. Sometimes, there's a philosophy that needs to be shared by the whole team to work effectively. I need to know all of that in order to effectively extend the program. There are also times (though less common) that I believe comments are needed to understand even the most clearly-written functions. This is usually when one needs background knowledge to understand the function. For example, a mathematical derivation isn't obvious when you're staring at a line of trig functions. At the very least, code like that needs a reference to a Wikipedia article or a book.

by T-hawk 13y ago

robomartin 13y ago

> code should be self-documenting Which is a myth. Try to come back to code five years and three languages later and see how self-documenting it is. It isn't. I could maybe --possibly-- stretch disbelief and accept that if someone works with one language and one platform for a long time the code will be self documenting to that person or that team. This is not the case for multi-technology projects with generations of people touching the code base. I'll give you a very concrete example. About fifteen years ago we spent three months authoring a tool in Visual Basic for Applications (VBA). This tool was used to automate certain aspects of the EDA (electronics design software) tool we were using at the time. The custom software was needed in order to vastly improve productivity with 1,000+ pin chips. The VBA tool effectively linked Excel with PCAD and reduced a twelve hour task to less than an hour. Well, I have not touched VBA in probably fifteen years. The code is full of comments about the very things I described in my prior post: intent, design, thoughts, ideas, enhancements, problems, etc. After fifteen years of not touching the language or the application I can jump into that code base and be up and running within not much more than an hour. It is hard to place a number on the value this adds to a project. It is nothing less than huge when it comes to supporting, maintaining, migrating and enhancing it. > "x+=5; //add 5 to x" Clearly the domain of morons.

iloveponies 13y ago

The idea that code be "self-documenting" is naive at best. Action does not necessarily infer intention, and without explanation can lead to assumption. To reach the code we end up committing a process of thought should have occurred by those who wrote it. For some things such as "boilerplate" code this may not be seen as significant. For others of increased complexity like explaining interactions between two pieces of logic, performing a complex set of logic or the expected usage of an externally provided interface comments are in my opinion essential. In contrast to what you've said I completely disagree with the notion that the "best code transcends the need for comments". I'd argue the best type of code has the most effective comments in line with code to ensure the next person can gain with the least amount of effort clear understanding of both the rationale and of the functionality that lead to what they see before them.

crpatino 13y ago

> What you describe about the development process, ... , is important but doesn't really belong in the source code. Except that in really big/successful projects, the proper places are outdated specs that end up buried in obscure unindexed archives. This can happen for a lot of reasons, technical debt, intellectual property acquisition, erosion of institutional knowledge due to personnel attrition, etc. On the other hand, source code is forever. It is the thing that you cannot unknowingly get rid off without getting rid of (your ability to update) the product itself. > Da Vinci didn't write on the back side of the Mona Lisa the production process for his paints. If you were a curator of the Louvre Museum, your job would have been easier if he did.

davidcuddeback 13y ago

> The counterargument is that code should be self-documenting. If code is complicated enough to need comments, refactor it. Behavior should be obvious from function and variable names. If you can't say what a method does in its name, it's too big. The best code transcends the need for comments. I used to believe that too, but I now believe that that point-of-view only addresses the accidental complexities of reading code. Don't get me wrong, descriptive function and variable names are great and make understanding code much easier. But I think it misses the forest (program structure) for the trees (functions). Where I get off that train is when trying to understand a program's structure. How do the modules decompose the problem being solved? Why was it designed a certain way? There's usually a combination of technical and domain knowledge that influenced the design. Sometimes, there's a philosophy that needs to be shared by the whole team to work effectively. I need to know all of that in order to effectively extend the program. There are also times (though less common) that I believe comments are needed to understand even the most clearly-written functions. This is usually when one needs background knowledge to understand the function. For example, a mathematical derivation isn't obvious when you're staring at a line of trig functions. At the very least, code like that needs a reference to a Wikipedia article or a book.