Notes on code cleansing: Comments

Notes on code cleansing: Comments

Preface: I used to be convinced that "comments in a good code should take at least half of the size". I am also very proud to add javadoc to every function; I am sorry for the "bad habit" of writing code without comments. However, after reading the "Comments" section of Robert, I was annoyed and began to review and optimize my code. I have started to follow the "don't comment on bad code-rewrite it" principle.

Maybe you are a good person who will constantly optimize and improve the Code. However, you will often ignore comments, just as below:

/*** Set bidding. ** @ param orderFromClient * @ return */private Message callAuction (SelfOrder orderFromClient, long B, JadeInfo jadeInfo ){

The method parameter has changed. However, there is only one parameter in the javadoc comment.

I personally have been deeply influenced by Robert so that the code can tell it exactly what it is doing, not comment. However, many of us, including those who read this book, think that programmers who write comments are good programmers. Of course, this does not include those who only write bad code.

Elaborate with code

Let's compare the two types of code:

Public void pause () {if (isNotAction () {return ;}/ *** no transaction items on holidays or the same day, the server does not perform operations */private boolean isNotAction () {if (isHoliday |! HasTradingJade) {return true;} return false ;}

Public void pause () {// No goods are traded on holidays or the same day, and the server does not perform operations if (isHoliday |! HasTradingJade) {return ;}}

I think the first one is better. Because holidays and non-transactional goods mean that the server does not need to run on the same day, isNotAction is better.

Good comments

Interpreting intentions

/** Sort the variable amount of funds by user ID to ensure that no deadlock occurs when multiple threads update the fund field at the same time */@ Override public int compareTo (VarialMoneyUser o) {return this. getUid (). compareTo (o. getUid ());}

I think this annotation is not bad. It illustrates the intention to use compare.

TODO comments
Sometimes, we need to do something, but we haven't done it yet, so we can use TODO, so that IDE will manage these TODO, and of course there are FIXME tags, it indicates that we do not know how to optimize or improve some problems for the moment.

Trade. setDjzj (BigDecimal. valueOf (0); // FIXME freeze funds to be implemented // TODO calculates the profit and loss of the account. Based on the risk control level, it indicates the account that needs to be reminded, restricted, and closed on the next day.

However, it should be noted that regular back-check, eclipse provides the slice function, you need to delete those useless TODO

Bad comments

Muttering

Public void dailyUpdateSystemData () {// update the membership information once every day. AllMembercoes. init ();

The preceding annotations are unnecessary.

Additional comments

/*** @ Description: Obtain the daily report of a specified date */public QuotationDailyReport getQuotationReportByDateAndScode (QuotationDailyReport);/*** @ Title: addQuotationReport * @ Description: add daily report * @ param tradeReport * @ return */public int addQuotationReport (QuotationDailyReport tradeReport);/*** @ Title: getLastQuotationReport * @ Description: obtain the information of the previous quote Report of the specified product * @ param map * @ return */@ SuppressWarnings ("rawtypes") public QuotationDailyReport getLastQuotationReport (Map map );

These annotations are more terrible than those without annotations. Actually, you know what to do when you look at the method name. adding annotations is a waste of time.

Ps:I used to like to add such comments. I wish to add comments to every method. But since I understood it, the method name itself should represent what the method will do, I hate my past ridiculous behavior..

Misleading comments

This is terrible. In many cases, the comments and code expressions are the opposite, or the comment is irrelevant. In short, it is easy to confuse.

// Set isreload to true after, reload the configuration, private void updateReloadStatusTrue (){

This annotation is intended to be very friendly and prompts that the method is executed after, but I can refer to the context and cannot find any information.

This will be better.

/*** Setting isreload to true indicates that the configuration service and commodity service can be reloaded */private void updateReloadStatusTrue () {reload = true; ConfigService. isReload = reload; JadeInfoService. isReload = reload ;}

Compliant comments

Oh, this kind of annotation mostly occurs in the method. I used to be very keen on this annotation, and now I know what's terrible.

/*** @ Title: updateQuotation * @ Description: Modify the quote information of the specified product * @ param quotation */public void updateQuotation (Quotation quotation) {this. quotationMapper. updateQuotation (quotation );}

Comments of title and param have two disadvantages:

Too redundant. Can't the method itself tell me? This hinders refactoring. Comments will not change immediately when the method name and parameter name need to be restructured or added.

Log Annotation

In the past, we liked to add the following comments to the Code:

// Start update by maweiqing // If a message is received, it indicates that the client has performed an operation, and the session time data = CryptUtil will be updated. encrypt (data, SessionManager. getSession (). getSessionId ()). getEncryptKey (); // end update by maweiqing 2015-05-27

After seeing Robert's suggestion, I really suddenly realized that such code also needs the SVN Code Manager. Why? SVN will naturally allow you to enter your reasons for modification, as well as automatically display the signature and date.

Nonsense comments

// Id column private Integer id; // user id private Integer userId; // user name private String userName;

Such annotations are completely unnecessary. Do you think there are any such annotations?

/**  * @return the id  */ public Integer getId() {  return id; } /**  * @param id  *            the id to set  */ public void setId(Integer id) {  this.id = id; }

Also, using this bean annotation generated by IDE, I really regret why I was thinking this way. Is it obvious that adding this annotation makes myself professional.

Location tag

Although I have not found it in my own code, I have done this before.

//xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx//aaaaaaaaaaaaaaaaaaaa

Commented out code

Oh, obviously, I have made another move. Previously, I especially liked to leave the so-called useful code in the code, and it was wrong at all. But since I saw Jeff's blog, I began to delete the comments of the Code. Today I see Robert's article, and I feel that these great programmers will have such similar truth.

If you have such comments in your code, delete them as soon as possible, which is too harmful.

Summary: I think that Robert's article has increasingly influenced me and changed many bad habits.