PHP编码规范-php coding standard
|
Interface and Implementation Documentation There are two main audiences for documentation: Class Users Class Implementors With a little forethought we can extract both types of documentation directly from source code. Class Users Class users need class interface information which when structured correctly can be extracted directly from a header file. When filling out the header comment blocks for a class, only include information needed by programmers who use the class. Don't delve into algorithm implementation details unless the details are needed by a user of the class. Consider comments in a header file a man page in waiting. Class Implementors Class implementors require in-depth knowledge of how a class is implemented. This comment type is found in the source file(s) implementing a class. Don't worry about interface issues. Header comment blocks in a source file should cover algorithm issues and other design decisions. Comment blocks within a method's implementation should explain even more.
目录文档所有的目录下都需要具有README文档，其中包括：
该目录的功能及其包含内容
一个对每一文件的在线说明（带有link），每一个说明通常还应该提取文件标头的一些属性名字。
包括设置、使用说明
指导人民如何连接相关资源：
源文件索引
在线文档
纸文档
设计文档
其他对读者有帮助的东西 考虑一下，当每个原有的工程人员走了，在6个月之内来的一个新人，那个孤独受惊吓的探险者通过整个 Use a Design Notation and Process Programmers need to have a common language for talking about coding, designs, and the software process in general. This is critical to project success. Any project brings together people of widely varying skills, knowledge, and experience. Even if everyone on a project is a genius you will still fail because people will endlessly talk past each other because there is no common language and processes binding the project together. All you'll get is massive fights, burnout, and little progress. If you send your group to training they may not come back seasoned experts but at least your group will all be on the same page; a team. There are many popular methodologies out there. The point is to do some research, pick a method, train your people on it, and use it. Take a look at the top of this page for links to various methodologies. You may find the CRC (class responsibility cards) approach to teasing out a design useful. Many others have. It is an informal approach encouraging team cooperation and focusing on objects doing things rather than objects having attributes. There's even a whole book on it: Using CRC Cards by Nancy M. Wilkinson. Using Use Cases A use case is a generic description of an entire transaction involving several objects. A use case can also describe the behaviour of a set of objects, such as an organization. A use case model thus presents a collection of use cases and is typically used to specify the behavior of a whole application system together with one or more external actors that interact with the system. An individual use case may have a name (although it is typically not a simple name). Its meaning is often written as an informal text description of the external actors and the sequences of events between objects that make up the transaction. Use cases can include other use cases as part of their behaviour. Requirements Capture Use cases attempt to capture the requirements for a system in an understandable form. The idea is by running through a set of use case we can verify that the system is doing what it should be doing. Have as many use cases as needed to describe what a system needs to accomplish. The Process Start by understanding the system you are trying to build. Create a set of use cases describing how the system is to be used by all its different audiences. Create a class and object model for the system. Run through all the use cases to make sure your model can handle all the cases. Update your model and create new use cases as necessary. Open/Closed Principle The Open/Closed principle states a class must be open and closed where: open means a class has the ability to be extended. closed means a class is closed for modifications other than extension. The idea is once a class has been approved for use having gone through code reviews, unit tests, and other qualifying procedures, you don't want to change the class very much, just extend it. The Open/Closed principle is a pitch for stability. A system is extended by adding new code not by changing already working code. Programmers often don't feel comfortable changing old code because it works! This principle just gives you an academic sounding justification for your fears :-) （编辑：焦作站长网） 【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容! |
