Target Audience:
Anyone using the PHP programming language who wants to learn how to self document their code. Anyone interested in PHP Good Practices and Coding Standards.
Languages Used:
PHP 5+
Related Material:
Introduction:
In computer programming, self-documenting (or self-describing) is a common descriptor for source code that follows certain loosely-defined conventions for naming and structure. These conventions are intended to enable developers, users and maintainers of a system to use it effectively without requiring previous knowledge of its specification, design, or behavior
From Wikipedia, the free encyclopedia
Imagine a world where every country used a different system for telling time, or tracking dates. The United States uses a 24 hour clock and our common calendar, but let’s say France uses a clock that doesn’t have hours at all, but instead some other unit of measurement. How would people interact? How would anyone get anything done in any reasonable amount of time? Having a standard system of telling time makes interactions around the world much easier.
Self-Documenting code is a process of following an ‘accepted’ standard for the purpose of making your code more readable by others who adopt the same standards. This is most commonly the case in large organizations that employee teams of programmers who all have to interact and work with one another.
But even if you are working alone, meeting these standards is still important. It not only allows you to easily read and understand distributed code that meets those standards, but it also gives a certain amount of credibility to your own work. When someone sees that you are using good coding practices, your code immediately gets more respect and a certain amount of credibility that says ‘I know what I am doing’.
It doesn’t matter if you are working on a big team and looking for a way to increase productivity, or the solo programmer looking to make a name for themselves, using good practices will advance your career. In this article we will talk about how you can self-document your code so that others can read it and understand it easier giving it more credibility.
Rule #1. Use The Naming Conventions!
Naming Conventions are a set of ‘guidelines’ defining what case is used when naming elements of your code. The purpose is to keep your code consistent, not only with yourself, but with other as well. Consistent code means easier to read code. Easy to read code is a step towards Self-Documented code.
Each language has a language specific Naming Convention. For more information on Naming Conventions in php please read ‘PHP Good Practices 1 – Naming Conventions‘.
Rule #2. Keep It Simple, Name It Smart!
What case to use when naming things is one thing, but what you name them is also very important. When you think of a computer program as being made up of things that are a reflection of real life, it becomes easier to determine what to name your class, variables, functions and other code elements.
This rule says keep it simple! This means long over detailed names are no good. Don’t use 5 words to say what you can say in 2. Have you ever seen variables with names like ‘ShoppingCartProductCategory’ or ‘ApplicationUserLoginName’? These names leave little quessing as to what these variables represent, but the same could be said with simply ‘ProductCategory’ or ‘LoginName’. The point is to much detail does NOT help make your code more readable. Keep It Simple!
The second part of this rule says to name it smart. This means pick a name that makes sense. Pick a name that really describes in the simplest clear way possible, what you are naming. If you are building a class for your shopping cart application then name it something that describes the class like ‘Cart’ or even ‘ShoppingCart’, but don’t use names like ‘Application’ or ‘MainClass’.
This is equally important for variables. When you declare a variable, it is for a purpose. Name that variable in a way that describes that variables purpose. If the variable is simply storing data then describe the data being stored. If you have a variable that needs to hold the name of your user then a name like $userName would be appropriate.
By naming your code elements in a way that describes there purpose in the application, you are documenting your application using it’s code. This is probably the most important rule for self-documenting your application. Keep your names simple yet clear to the purpose, and you will be on your way to cleaner code.
Rule #3. Use Comments but Don’t Abuse Comments.
Comments are a great way for the programmer to leave notes for themselves, or for others who may look at their code. Although this is a great tool, it is often not used at all, or way overused. Not leaving comments is like giving someone all the materials to make a shelf, but no instructions on how to put it together. Leaving to many comments is like giving someone all the materials to make the shelf and then provide an instruction manual for how to read the instruction manual.
Both of these practices are equally bad. Comments have a purpose and should be used. However if you are self-documenting your code by using names that make sense and following some sort of naming convention, then most of your code should not need comments. I will say that again, most of your code Should Not Need Comments.
Most applications have a few pieces of complicated code and a whole lot of simple code. Simple code normally requires little or no comments. leaving a comment like ‘Building Product Array’ right before you declare a variable named $product and assign it as an array, is pointless. Clearly we can see you are creating a new Array named product that will probably contain products.
Use comments to describe pieces of complicated code that can not easily be comprehended at a glance. Building a complicated formula from dynamic input or processing complex data types with recursive functionality might require a quick comment.
When a comment is needed Remember Rule #2! Just like other code elements, comments need to be clear but simple. No one wants to read a book to understand your 15 lines of pattern matching and comparisons only to find out you simply parsing out garbage from some data somewhere. Leave a quick comment ‘Parsing out markup’. Now I don’t have to keep track of variables in my head while trying to read your program logic. I can tell from your comment what this block of code does.
Note! Self-Documenting is NOT the same as Document Generation!
Document generation is where special comment tags are used in order to provide further details on functions, classs or other code elements. Applications like PHPDoc read your comment tags and generate documentation from those comments. This practice is usefull, however is not what is considered Self-Documenting.
Comment blocks for document generation will be covered later in this article series. Remember that Self-Documenting code is code that does not require additional comments or documentation to understand the logic in the code. Comments are only considered a part of Self-Documentation when used correctly, clearly, and only as needed.
It is ok to comment block your code for the purpose of Document Generation or even to provide information to your auto-complete feature within your IDE. Just don’t confuse document generation with Self-Documenting and you will be fine.
Wrap Up!
Remember the concept is to provide clean, clearly understandable, consistent code for the purpose of productivity while working with other programmers, or to give credibility to your own code. Either way, Self-Documenting your code will advance you in your career if you take it seriously and do it write.
— Live, Learn, Share —
Helpful Books:
Shell Scripts 