Document Everything

Even though a programmer may write good code, the software may be of poor quality because the programmer failed to document the code clearly. A program of complexity will often have several programmers working to develop and maintain it, but poor documentation can make software projects hard or impossible to maintain. Programmers should always document their code well so that the software will be easier to maintain and extend.

Programmers should properly name all variables, functions, and class objects used in code. Variable names should be named according to their purpose so that the purpose of the variables will be obvious and clear throughout their lifetime. Programmers should generally avoid variable names like x, y, and z. Like variables, functions should also be named according to their purpose, and they should have clear in and out parameters. In addition, classes should be named according to their purpose or relationship. By using proper naming of variables, classes, and functions, programmers will create easier to read code.

Besides names, programmers should always comment the purpose of every function. Every single function in code should be commented to illustrate the intended purpose of the function in a complete sentence. For example, “// Function HexToDec – takes a hexadecimal number as input and outputs the number in decimal.” Function parameters should also be documented to clearly express expected input and output. Processes inside of the function should also be documented to describe how the function obtains its results. Since some functions can be very complex, it is very important to illustrate the process being used by the function. Properly documenting functions can lead to higher quality software and easier maintenance.

Like functions, programmers should comment every class. Class member data should be clearly named so that other programmers can better understand its usage in the class. Class constructors, deconstructions, overloading operators, and member functions should be well defined and commented to illustrate their purpose. Every class should be commented to illustrate the intended purpose of the class, and it should contain any necessary information for clients so that they can quickly implement the class. Since object oriented programming can lead to code reuse, documentation in classes are essential.

In conclusion, programmers should pay particular attention to the documentation of their software project so that they can maintain clarity throughout their code. When programmers fail to properly document their code, the resulting software is often of poor quality. Even though many people believe programming is only about writing code, writing documentation is also a very important part of the process of software development.