The purpose of annotation is to improve the later maintainability of the code , That is to say, we spend the current working time in exchange for saving more time in the future .
One time code , Code that doesn't need to be maintained in the future doesn't actually need to be annotated .
Clear and simple structure , Easy to maintain code can be written with little or no comments , Writing too many comments will reduce work efficiency .
The more complex the code, the less maintainable it is , The more uneven the defenders are , The more important it is to write notes carefully .
Judgment note , It's easy to verify that documents are not written enough . If the code is maintained by itself in the future , Find your own code a few years ago , See if it's easy to see , Think about whether it's easy to change some functions . I've seen myself 10 Year ago code , Except for the low level writing disorder in some places , It's easy to see . If the code is maintained by other colleagues , We need to have systems to verify each other's notes , Is the code clear .
Engineering practice is always complicated . The problems we encounter in our life are actually more troublesome .
First of all, I'm short-sighted , Can't see or despise the significance of annotation to the future , Or believe too much in your ability to understand , I don't want to write notes . This tendency is difficult to correct , It might be helpful for him to maintain the code he wrote a long time ago .
And it's because the programmers that will be maintained in the future are not themselves , So writing notes becomes reducing your own performance and improving others' performance , This kind of thing needs sages to do well , It's really painful that we ordinary people take the initiative to do this , Only with the aid of assessment system . This assessment system is not easy to implement , Because of the comments , The effect of documents is hard to quantify , Not likely to be understood by leaders , It's not likely to be , Product and other department colleagues understand , So unless it is determined that the future benefits will be attributed to the team , Otherwise, the team has no motivation to restrain itself at present .
If the underlying programmer changes frequently , The team leader is required to manage the notes , If the group leader himself changes frequently , Then it needs a higher level of management to restrain . And so on , If one level of management is not stable enough , Unable to get the future benefits of annotations , And his superior leaders have no proper institutional perception , To compensate for this part of the annotation , Note that this work will not work well .
In fact, this part is easy to improve in daily management , According to the specific situation , Develop appropriate management system , This part can be controlled .
And there's even worse reluctance to write notes , Reasons for documentation , Some people will deliberately let the code be read by themselves , It's hard for others to understand , This will help you improve your position . This kind of person is still trying to find out earlier , Get rid of it earlier .