敏捷开发的必要技巧：将注释转为代码

摘要:
本文作者通过实例介绍了敏捷开发的必要技巧：将注释转为代码. 

示例 

   这是一个会议管理系统. 在会议中,每个参会者都会戴一个牌子,这牌子上面有这个参会者的信息(比如姓名之类的).在这个系统中,Badge这个类用来存放这个参会者的信息.请看一下下面的代码跟注释: 

    //存放参会者身上戴的牌子所显示的信息.     
public class Badge {
         String pid;  //参会者 ID
        String engName; //英文全名
        String chiName; //中文全名
        String engOrgName; //所在部门英文名称
        String chiOrgName; //所在部门中文名称
        String engCountry; //部门所在国家的中文名称
        String chiCountry; //部门所在国家的英文名称
        //***********************
         //构造函数. 
        //根据参会者的id,去数据库取出该参与者的信息. 
       //***********************
        Badge(String pid) {
            this.pid = pid; 
           //*********************** 
           //取出参会者
            //***********************
            ParticipantsInDB partsInDB = ParticipantsInDB.getInstance(); 
           Participant part = partsInDB.locateParticipant(pid); 
           if (part != null) {               //取出参会者的英文全名
              engName = part.getELastName() + ", " + part.getEFirstName();               //取出参会者的中文全名
              chiName = part.getCLastName()+part.getCFirstName();
               //*********************** 
              //取出所在部门跟国家. 
              //*********************** 
              OrganizationsInDB orgsInDB = OrganizationsInDB.getInstance();               //取出所在部门的id
.               String oid = orgsInDB.getOrganization(pid); 
              if (oid != null) { 
                  Organization org = orgsInDB.locateOrganization(oid); 
                  engOrgName = org.getEName();  
                 chiOrgName = org.getCName(); 
                  engCountry = org.getEAddress().getCountry(); 
                  chiCountry = org.getCAddress().getCountry(); 
               }
            }
         }
         ...     } 

将注释转换为代码,让代码足够清楚到可以表示注释

我们先看一下第一个注释: 

    //存放参会者身上戴的牌子所显示的信息.     public class Badge {         ...     } 

    我们干嘛需要这个注释呢?因为程序员认为"Badge"这个类名不足以让读代码的人清楚这个类的作用,所以就写了这个注释. 那如果我们直接将注释所表达的一些信息放在类名里面的话,就没有单独写注释的必要了.比如:: 

    public class ParticipantInfoOnBadge {         ...     } 

    其实很多人肯定会问?难道写注释不是一个好的编程习惯吗?这问题很好,我也想知道.在解释之前,我们先把这个示例中所有的注释都转为代码先.

将注释转换为变量名

Consider:     public class ParticipantInfoOnBadge {
         String pid;  //参会者 ID 
        String engName; //英文全名
        String chiName; //中文全名
        String engOrgName; //所在部门英文名称
        String chiOrgName; //所在部门中文名称 
       String engCountry; //部门所在国家的中文名称 
       String chiCountry; //部门所在国家的英文名称 
       ...     } 

这里,我们就像对属性的注释,转化为属性名, 比如: 

    public class ParticipantInfoOnBadge {
         String participantId; 
        String participantEngFullName; 
        String participantChiFullName;  
       String engOrgName;  
       String chiOrgName; 
        String engOrgCountry;  
       String chiOrgCountry;  
       ...      } 

对参数的注释,转化为参数名

看看: 

    public class ParticipantInfoOnBadge {
         ... 
        //***********************
         //构造函数.
         //根据参会者的id,从数据库取出该参与者的信息. 
       //***********************
         ParticipantInfoOnBadge(String pid) {
            this.pid = pid; 
            ... 
        } 
     } 

比如: 

    public class ParticipantInfoOnBadge { 
        ... 
        //***********************
         //构造函数. 
        //从数据库取出该参与者的信息. 
       //*********************** 
        ParticipantInfoOnBadge(String participantId) {
            this.participantId = participantId; 
            ... 
        }
      } 

[1]   

【责编:Peng】

--------------------next---------------------