Comments in code are quite often a code smell. Let’s see what is suboptimal about comments and talk about some strategies to avoid them.
Comments in code are quite often a code smell. Let’s see what is suboptimal about comments and talk about some strategies to avoid them.
This is a little bit of a case in point of why documentation should not be written by the teacher. It should be written by the student. The student takes no knowledge for granted and so will only repeat themselves insofar as they need to. The teacher will either repeat themselves consistently, or just leave massive gaps due to their preexisting knowledge. Even though it wouldn’t be practical for a coder to have some student document their code, I feel like this still illustrates the point. Also it means you have to constantly put yourselves in the shoes of some future student, which seems like a good practice anyway.
I think this is also in line with my article, since not being able to put yourself into somebody else’s shoes (or even in yourself future’s ones) is the reason for so much bad comments. But adding a comment to every single line cannot be the solution either, at least not in a higher programming language.