3 ms·

This is one of the things that really bugs me about a lot of open source and Github code: almost no comments. It almost seems that there's a generation of pro

This is one of the things that really bugs me about a lot of open source and Github code: almost no comments. It almost seems that there's a generation of programmers being taught that comments are a waste of time. I really don't know where this trend comes from. Lazy? I don't want to believe that. For my purposes it is a huge negative mark if a programmer is not religious about commenting code. I will not hire someone like that. Why? Developing code is a huge financial investment, yes, but there are other metrics that are far more important than money. If you are doing something non-trivial it often requires a lot of thought, discussion, testing, experimentation, failures, iterations and decisions. Comments within code should be used to document some of this. Document intent, thinking, problem solving approach, corner cases, decisions, where/how it could be improved, performance notes, etc. This and the code become incredibly valuable. It means that months or years later someone can go back into the code and truly understand what it does, why it does it that way, where it came from and, perhaps, how it could be improved. You don't need to engage in a research project in order to pick-up where the last programmers left of and continue moving forward. In addition to that I firmly believe a well-commented code-base is far more valuable during an acquisition than a thousand files of code with hardly a comment. I can think of a number of Github projects I've come across with nearly zero comments. What you are looking at is dozens or hundreds of files vomited upon your hard drive that, yes, might perform a useful function at that point in time yet would be a nightmare to dive into to maintain them in any way. Before someone jumps down my throat: Just because something is FOSS it doesn't mean we should not critique such practices. If everyone took the time to thoughtfully document their code the FOSS ecosystem would probably evolve at a faster rate. Some of these packages are so dense they are virtually impenetrable without cubic hours of work deciphering the rats nest of files.

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
davidcuddeback 13y ago
> It almost seems that there's a generation of programmers being taught that comments are a waste of time. That might be true. I had at least one professor who discouraged comments. He said, "I know how to read code." I can understand that in his particular case, he didn't need documentation for higher-level understanding. He taught us the algorithms and data structures being used and he gave us a boiler plate design that we had to conform to. All we had to do was fill in the function bodies and write a main() function. Unfortunately, it's possible that some students might have adopted that as an overall attitude without recognizing that the context in which it was said invalidated the need for comments for any higher-level understanding. A lot of students looked up to this professor. That's just a single example. I have no idea how common this is.

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

davidcuddeback 13y ago

> It almost seems that there's a generation of programmers being taught that comments are a waste of time. That might be true. I had at least one professor who discouraged comments. He said, "I know how to read code." I can understand that in his particular case, he didn't need documentation for higher-level understanding. He taught us the algorithms and data structures being used and he gave us a boiler plate design that we had to conform to. All we had to do was fill in the function bodies and write a main() function. Unfortunately, it's possible that some students might have adopted that as an overall attitude without recognizing that the context in which it was said invalidated the need for comments for any higher-level understanding. A lot of students looked up to this professor. That's just a single example. I have no idea how common this is.