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

来源：互联网发布：网络红猫红小胖编辑：程序博客网时间：2024/05/17 04:36

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

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

Wingel 发表于 2006-12-25 09:35:35

作者:Wingel 来源:Wingel's blog

摘要:

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

这是一个会议管理系统. 在会议中,每个参会者都会戴一个牌子,这牌子上面有这个参会者的信息(比如姓名之类的).在这个系统中,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; 

            ... 

        } 
     }

将注释转换为方法的一部分

上面的构造函数中,有两句注释,第一句我们已经解决了,那么还有"从数据库取出该参与者的信息"? 这句注释描述了,这个构造函数是如何实现的(就是从数据库里面取出信息),我们将这句话转化:

    public class ParticipantInfoOnBadge { 

        ... 

        //*********************** 
        //构造函数. 
        //*********************** 
        ParticipantInfoOnBadge(String participantId) { 
           loadInfoFromDB(participantId);//现在,看一下这个构造函数内部,我们就能知道这个构造函数是做什么了吧. 
        } 
        void loadInfoFromDB(String participantId) { 
           this.participantId = participantId; 

            ... 

        } 
     }

删掉没用的注释

有时候,我们会碰到一些注释,很明显没什么用处的,比如:

    public class ParticipantInfoOnBadge { 

        ... 

        //*********************** 
        //构造函数. 
        //*********************** 
        ParticipantInfoOnBadge(String participantId) { 

            ... 

        } 
     }

就算去掉这些注释,我们也能看得出来,这是个构造函数.这个注释并没什么用处.
什么样的类是看代码的人最喜欢的?那就是简单易看的类.一个设计得好的类,能够让人家一眼就能出你这个类都有些什么东西,明白你这个类都做了一些什么事.如果看这个类的时候,要不停的将屏幕滚来滚去,而思维还要随屏幕的滚动跳转,无形中,看懂这个类需要花的时间就多了.
一个屏幕,差不多只能显示20行左右的代码,而这个没用的注释,一下子就占用了3行的代码,一些有用的信息反而被挤掉了(比如说代码),得不偿失啊!我看还是赶紧移除这个注释:


    public class ParticipantInfoOnBadge { 

        ... 

        ParticipantInfoOnBadge(String participantId) { 

            ... 

        } 
     }

将一部分代码重构成方法,用方法名来表达注释的意思

先看看下面这个注释:

        void loadInfoFromDB(String participantId) { 
           this.participantId = participantId; 
           //*********************** 
           //取得参会者的全名. 
           //*********************** 
           ParticipantsInDB partsInDB = ParticipantsInDB.getInstance(); 
           Participant part = partsInDB.locateParticipant(participantId); 
           if (part != null) { 
               //取得参会者的英文全名. 
               engFullName = part.getELastName() + ", " + part.getEFirstName(); 
               //取得参会者的中文全名. 
               chiFullName = part.getCLastName()+part.getCFirstName(); 
               //*********************** 
               //取得参会者所在部门和国家. 
               //*********************** 
               OrganizationsInDB orgsInDB = OrganizationsInDB.getInstance(); 
               //取得参会者被雇佣部门的id. 
               String oid = orgsInDB.getOrganization(participantId); 
               if (oid != null) { 
                  Organization org = orgsInDB.locateOrganization(oid); 
                   engOrgName = org.getEName(); 
                   chiOrgName = org.getCName(); 
                   engOrgCountry = org.getEAddress().getCountry(); 
                   chiOrgCountry = org.getCAddress().getCountry(); 
               } 
            } 
        }

现在我们已经看清这段注释要表达一些什么信息,如果要使代码跟注释一样清楚,我们可以将注释所解释的那部分代码抽取出来,做成一个方法,然后让方法名来表达注释的意思.如果可以的话,我们就不需要额外的注释了:

        void loadInfoFromDB(String participantId) { 
           this.participantId = participantId; 
           getParticipantFullNames(); //(取得参会者的全名,注意,我们已经将注释去掉了.)
            //*********************** 
            //取得参会者所在部门和国家. 
            //*********************** 
            //取得参会者被雇佣部门的id. 
           OrganizationsInDB orgsInDB = OrganizationsInDB.getInstance(); 
           String oid = orgsInDB.getOrganization(participantId); 
           if (oid != null) { 
               Organization org = orgsInDB.locateOrganization(oid); 
               engOrgName = org.getEName(); 
               chiOrgName = org.getCName(); 
               engOrgCountry = org.getEAddress().getCountry(); 
               chiOrgCountry = org.getCAddress().getCountry(); 
            } 
        } 
        void getParticipantFullNames() { 
           ParticipantsInDB partsInDB = ParticipantsInDB.getInstance(); 
           Participant part = partsInDB.locateParticipant(participantId); 
           if (part != null) { 
               //取得参会者的英文全名. 
               engFullName = part.getELastName() + ", " + part.getEFirstName(); 
               //取得参会者的中文全名. 
               chiFullName = part.getCLastName()+part.getCFirstName(); 
            } 
        }

此外,还有一个注释:"取得参会者所在部门和国家",也是可以重构在方法名里面的:

        void loadInfoFromDB(String participantId) { 
           this.participantId = participantId; 
           getParticipantFullNames(); 
           getOrgNameAndCountry(); //又抽取掉了一个注释
        } 
        void getParticipantFullNames() { 
           ParticipantsInDB partsInDB = ParticipantsInDB.getInstance(); 
           Participant part = partsInDB.locateParticipant(participantId); 
           if (part != null) { 
               //取得参会者的英文全名. 
               engFullName = part.getELastName() + ", " + part.getEFirstName(); 
               //取得参会者的中文全名. 
               chiFullName = part.getCLastName()+part.getCFirstName(); 
            } 
        } 
        void getOrgNameAndCountry() { 
           OrganizationsInDB orgsInDB = OrganizationsInDB.getInstance(); 
           //取得参会者被雇佣部门的id. 
           String oid = orgsInDB.getOrganization(participantId); 
           if (oid != null) { 
               Organization org = orgsInDB.locateOrganization(oid); 
               engOrgName = org.getEName(); 
               chiOrgName = org.getCName(); 
               engOrgCountry = org.getEAddress().getCountry(); 
               chiOrgCountry = org.getCAddress().getCountry(); 
            } 
        }

抽取出方法,放于另一个类

请看一下下面这两个注释:

    public class ParticipantInfoOnBadge { 

        ... 

        void getParticipantFullNames() { 
           ParticipantsInDB partsInDB = ParticipantsInDB.getInstance(); 
           Participant part = partsInDB.locateParticipant(participantId); 
           if (part != null) { 
               //取得参会者的英文全名. 
               engFullName = part.getELastName() + ", " + part.getEFirstName(); 
               //取得参会者的中文全名. 
               chiFullName = part.getCLastName()+part.getCFirstName(); 
            } 
        } 
     }

因为程序员觉得,这些代码片段还是不够清楚,所以还是要用注释还解释它们. 但这回移除注释时,我们会将抽取出来的方法,放到Participant这个类里面,而不是ParticipantInfoOnBadge了:

    public class ParticipantInfoOnBadge { 

        ... 

        void getParticipantFullNames() { 
           ParticipantsInDB partsInDB = ParticipantsInDB.getInstance(); 
           Participant part = partsInDB.locateParticipant(participantId); 
           if (part != null) { 
               engFullName = part.getEFullName(); //将职责交给domain自己,也就是Participant.
               chiFullName = part.getCFullName(); 
            } 
        } 
     } 
    public class Participant { 
        String getEFullName() { 
           return getELastName() + ", " + getEFirstName(); 
        } 
        String getCFullName() { 
           return getCLastName() + getCFirstName(); 
        } 
     }

用注释去命名一个已经存在的方法

请看下面的注释,也是这个例子中的最后一个注释了:

    public class ParticipantInfoOnBadge { 

        ... 

        void getOrgNameAndCountry() { 
           OrganizationsInDB orgsInDB = OrganizationsInDB.getInstance(); 
           //取得参会者被雇佣部门的id. 
           String oid = orgsInDB.getOrganization(participantId); 
           if (oid != null) { 
               Organization org = orgsInDB.locateOrganization(oid); 
               engOrgName = org.getEName(); 
               chiOrgName = org.getCName(); 
               engOrgCountry = org.getEAddress().getCountry(); 
               chiOrgCountry = org.getCAddress().getCountry(); 
            } 
        } 
     }

我们之所以要用这个注释"取得参会者被雇佣部门的id",是因为这个方法名"getOrganization"取得不够清楚. 所以,我们将注释表达的信息,放在这个方法名里面:

    public class ParticipantInfoOnBadge { 

        ... 

        void getOrgNameAndCountry() { 
           OrganizationsInDB orgsInDB = OrganizationsInDB.getInstance(); 
           String oid = orgsInDB.findOrganizationEmploying(participantId); 
           if (oid != null) { 
               Organization org = orgsInDB.locateOrganization(oid); 
               engOrgName = org.getEName(); 
               chiOrgName = org.getCName(); 
               engOrgCountry = org.getEAddress().getCountry(); 
               chiOrgCountry = org.getCAddress().getCountry(); 
            } 
        } 
     } 

    public class OrganizationsInDB { 

        ... 

        void findOrganizationEmploying(String participantId) { 

            ... 

        } 
     }

pdf下载：http://www.blogjava.net/Files/Wingel/敏捷开发的必要技巧第1,2章.rar

0 0