How can you leave comments in the step with the code?

Possible duplicate:
How do you like your comments?

G'day

Edit 2:. In the event that general thoughts on the comment code arise in the above question, I'm more interested in ways to ensure that the code and comments remain in step.

I read how Steve McConnell's excellent Code Complete books " Code Complete " and " Code Complete 2 " and wondered if people have any other suggestions for saving comments and code in a step.

Aside from a great technique for eliminating the need for commenting, this blog post by Jeff about commenting does not really apply to keeping things in step.

My commentary mantra can be summed up with the basic idea of ​​the expression "what the code below cannot say."

+4
source share
3 answers

As you say, comments should express what is no longer apparent from the code (the reason that the code was as it is, the approaches that were tried and discovered, had flaws that led to the code being the way he is now, etc.)

But in a more general sense, think that the code is logically grouped into related pieces. Namespaces, classes, methods, blocks, strings. These fragments form a hierarchical overview of the application. Therefore, by commenting on the blocks and giving a general overview of what they are doing, you can summarize the code quickly and simply so that someone else can find a bit that suits them, understand, and then use or modify it effectively and with minimal risk failure.

So, explaining that File.Open opens a file is useless.

But explaining that a block of 10 lines of code will find, open, read and save the settings for your application, you will save a reader who must really read and decode the full text. In a few words, they can understand the whole purpose of the code and know if they need something they need to deepen. Or, if they want to call the code, they will understand what it does and how to use it - again, without having to delve into the finer details of how it reaches its behavior.

Thus, the commentary should begin with any important piece of code (at any / all levels described above), where the summary will save the reader who needs to read the code in order to clearly understand what it is doing. And anywhere you need to comment on code to explain how and why it does what it does.

Remember that your comment describes the code to someone who has not seen this before. Or yourself, when you review it after 6 months. A few well-chosen words can save hours of work trying to decipher a complete understanding of some code.

+1
source

Just comment on things that you might not find too intuitive for yourself if you come and see your code after 6 months!

Thus, you are doing a service for your future (usually you will be the one who later visits the older parts of the code), as well as the other who the latter can support your code :)

+1
source

When you find that you want to include a comment, ask yourself why this part of the comment is not in the native method with the method’s own name ... this way you will comment on the code using the method name and divide it into smaller steps to make it clearer.

+1
source

Source: https://habr.com/ru/post/1306584/


All Articles