Basic OO programming skills (3) Comments

Basic OO programming skills (3) Comments

 

1. avoid relying on Annotations to avoid refactoring

Note can make the code easier to understand, but in many cases, it will make the programmer too "dependent" comment and reduce the degree of self-description of the Code.

Need to comment? Is the code name not clear enough, or the abstract level of the Code is messy, or is the motivation of the Code not clear enough? The qualified Code itself generally does not require additional comments.

 

For example:

//newPasswordMUST at least 6 digitsUser.Password= newPassword ;

 

It can be reconstructed as follows:

 

privateconst string PASSWORD_MIN_LENGTH = 6;publicvoid ChangePassword(string newPassword){Assert.IsTrue(newPassword.Length>= PASSWORD_MIN_LENGTH );User.Password= newPassword;}

 

Another example is:

 

//Employeeis eligible to retireif(Employee.Age> 65 && Employee.Payed){...}

 

Reconstruction:

if(Employee.EligibleToRetire){ } privatebool EligibletoRetire{get{returnthis.Age > 65 && this.Payed;}}

 

When to use annotations

Since refactoring is the main method to make the code clearer, when will annotations be used?

1. Company copyright description

// Copyright (C) 2003,2004,2005 by XXX. All rightsreserved.

 

 

2. Sample

var date = new Date("dd-MM-yyyy"); // sample: 10-11-2014

 

3. Some necessary annotations

For example

if(...){return 0 ;}return 1 ; // 1: eligible 2 :non-eligible

 

Another example is to test the performance in unit testing.

For (VAR I = 0; I <1000/* One thousand concurrent threads to simulate high concurrency */; I ++ ){}

 

Another example is the case of multithreading (remind you to consider multi-threaded access in the shared resource environment ):

//do not forget take care of multi-thread scenariosvar resource = new ShareResource();

 

4. Todo

For example:

User.Login();//TODO : finish order logic

 

Unnecessary comments 1. Use comments to avoid reasons for imperfect code

try {LoadFiles();}Catch(IOException exp){//Do nothing}

If Swallow is abnormal, why should we capture it? There is no need to use a comment as a reason to do nothing.

 

2. Comment

//1.Student Age > 6//2.Region is validpublic void IsEligible(Student student){...}

 

There is no need to write the implementation logic of the Code in the function header. You can use annotations to guide yourself to write the code implementation. However, you are advised to clear the code in time to avoid misleading code inconsistency after the code logic is modified. After all, the Code is the only one that won't lie. (Software UI, documents, and comments all lie ")

3. There is no need to write a description for every property or member.

 

/*** The Manager implementation with which this Containeris* associated.*/protected Manager manager = null; /*** The cluster with which this Container is associated.*/protected Cluster cluster = null; /*** The human-readable name of this Container.*/protected String name = null;

 

Obviously, if you write comments for each field, attribute, and method, it looks very uniform, but it seriously affects the readability of the Code. The Code itself should be capable of self-interpretation. If comments are needed to make up for it, refactoring should be considered.

 

4. Unnecessary log comments

 

For example:

* Changes (from 11-Oct-2001)* --------------------------* 11-Oct-2001 :Re-organised the class and moved it to new package* com.jrefinery.date (DG);* 05-Nov-2001 : Added a getDescription() method, andeliminated NotableDate* class (DG);* 12-Nov-2001 : IBD requires setDescription() method,now that NotableDate* class is gone (DG); Changed getPreviousDayOfWeek(),* getFollowingDayOfWeek() and getNearestDayOfWeek() tocorrect* bugs (DG);* 05-Dec-2001 : Fixed bug in SpreadsheetDate class(DG);* 29-May-2002 : Moved the month constants into aseparate interface* (MonthConstants) (DG);* 27-Aug-2002 : Fixed bug in addMonths() method,thanks to N???levka Petr (DG);* 03-Oct-2002 : Fixed errors reported by Checkstyle(DG);* 13-Mar-2003 : Implemented Serializable (DG);* 29-May-2003 : Fixed bug in addMonths method (DG);* 04-Sep-2003 : Implemented Comparable. Updated theisInRange javadocs (DG);* 05-Jan-2005 : Fixed bug in addYears() method(1096282) (DG);

 

This annotation looks neat, and many companies are currently follow. In fact, it is completely unnecessary because source control has done the same thing for us. This annotation only reduces the readability of the Code, no one will check the information provided after a long time.

 

5. Noise comments need to be shielded

 /*** Default constructor.*/protected Student() {}

Who knows this is the default constructor?

 

Another example is:

/*** Returns the day of the month.** @return the day of the month.*/public int getDayOfMonth() {return dayOfMonth;}

 

Such a comment is completely unnecessary and meaningless if it is a standard.

 

6. Avoid signature comments

 

//added by Richard

 

The source control tool has done the same thing for us as the log annotation.

 

7. Avoid "temporarily commented out" code

 

InputStreamResponse response = newInputStreamResponse();response.setBody(formatter.getResultStream(),formatter.getByteCount());// InputStream resultsStream =formatter.getResultStream();// StreamReader reader = newStreamReader(resultsStream);//response.setContent(reader.read(formatter.getByteCount()));

 

It is often put there temporarily because it is "Unwilling" to delete it. Will it be used in the future? Remove it with determination. sourcecontrol will help you save it. It helps other coder to read it comfortably and avoid misleading.