re: I love to document my code. Am I doing it wrong? VIEW POST


Too many comments can make your code unreadable, it can make changes more difficult (since you need to update to comments as well). On the other hand with correct naming and coding style a lot of comments are totally unnecessary. You can read more about this topic in the Clean Code book of Robert C. Martin.



I've hear about the book and expected it to come up here. Although I generally love Uncle Bob books I'm a bit demotivated to read Clean Code. I kinda agree with what's explained in this article:

I always liked the idea to create functions and assign them a responsibility since it makes it much easier to reason about. I also tend to create functions that I know that will be reused, but I don't like much the idea of creating functions that I know for sure that will only be used 1 time.

I'm curious, when you say that it is unnecessary, do you mean that it is bad and should be removed as a consequence?



First of all: I think this topic is quite subjective, there's not absolute truth. And I would not suggest to follow the Clean Code book blindly, there are several situations when it doesn't worth.

If think you are talking about two topics, however they are connecting to each other I would suggest to discuss them separately:


What are the "bad" comment, which are not really necessary:
During my carrier I quite often met with such code:
speed = 30 //Setting speed to 40
What happened here? Someone set first to 40, and added a comment, which had totally no added value. Later on the software was not working as it should and an other colleague had to task to fix the behavior. He realized that the value of speed need to be changed at this point, but missed to change the comment (basically just avoided double work). Right now you have a totally inconsistent comment in your code base and most likely it never will be fixed.
It was just an example, but what I mean here: if you have "redundant" comments, then later on with time it can easily become a "misleading" comment, that's my experience with them. So I always try to write code, which is easily modifiable, so I'm avoiding all duplication and for me it belongs to the same category.

  1. Splitting functions: It really depends on the environment, for example in embedded environment introduction of new function can go against run time and it should be avoided. But in high level object oriented development the compilers are optimizing your code well and by the usage of private functions you are not messing up your public interface. Here I don't really see any point against splitting functions. But of course splitting down everything into 2 line long functions is not a good strategy. Here really my only point next to smaller and well-named functions is readability. Try to understand a function with 120 lines and multiple responsibility and try to understand the same functionality with broken down functions. Based on my experiences the second will be much faster and easier.
code of conduct - report abuse