Book a Free Consultation

Source Code Documentation

source code documentation

Source Code Documentation

Every advanced and evolving web app should have its own documentation. Documentation in form of a set of documents stored in a cloud or in a company’s local network, describes an app in its various aspects: frm more general, like business application, through interface operation, to details like structure and technologies used. It plays a very useful role facilitating stakeholders, for example programmers, who are new to the team, becoming familiar with application of individual components, and better understanding of basically every part of the system. But more “low-level”, though serving the same purpose type of documentation is source code documentation created in the PHP language we use with help of a tool known as phpDocumentor. Such documentation isn’t located in a separate text file, but in the comments.

Comment as a documentation

In every programming language there are comments, that are specially marked code fragments, that can contain any text entered by the developer, and which isn’t executed by the program as a command, but serves as a documentation regarding another fragment of the code: be it a single line known as a line comment, or more lines, known as block comment. It can also relate to a single method or a whole class. Those comments can contain some helpful information for other developers allowing to better understand our code or suggest future corrections. For example, such comments look like this:

Comments like this, however still widely used to describe certain situations regarding specific place in a file, started to reveal their defects over time. Because we can safely assume, every method we write will be used, changed and watched by other devs multiple times. And they are mainly interested in two things: what parameters does that method take and what does it give back, therefore we would have to give that information manually every single time, which would be very time consuming. That creates the need to standardize and automation of the process of creating of such code-documenting comments and that need is fulfilled by phpDocumentor.

phpDocumentor i PHPDoc                                                                

phpDocumentor is a library written in PHP programming language, available for example through PEAR repository or Composer package manager. Using it we can generate documentation, the structure of which is specified by the standard called PHPDoc. phpDocumentor parses (reads) the PHP file, separating individual constituent elements of the language and “pastes” matching comments, according to PHPDoc specification.

The first version of phpDocumentor has been created in 2000, and since 2012 a second version has been available. Each subsequent actualization operates next versions of the language, but usually it takes some time for phpDocumentor to keep up to the most recent version of the PHP language.

Using of PHPDoc isn’t of course required for scripts or apps to work correctly, but it gained so much popularity over the past few years, that it became an informal standard (known as de facto standard). Furthermore, since 2013, when PHP FIG (the organization establishing standards for the whole world of PHP) started to create a formal specification for PHPDoc (PSR-5), it becomes de iure standard, which has no relevant competition.

Standard in practice

PHPDoc allows adding a comment documenting the most important structure elements occurring in the PHP language, such as variables (including class fields), interfaces and classes. Documentation of a specific element is created by putting it in between comment delimiters: opening /**(double asterisk) and closing */. It can look something like this:

What we can see here is a defined method, which is most possibly used for tilting an image by specific angle. Thanks to documenting how the method works, we can know immediately, without thorough analysis of its “body”. As we can see, it takes as parameters: an Image object, containing an image, an integer number describing angle, desired direction of tilting and background color, which will be filling in the spaces, that the original image doesn’t cover anymore. Of course in that case we can extrapolate that data from default parameter value, but they’re not always set. Furthermore, we can quickly realize, that this method returns the same Image object with already tilted image. Thus, a mere glance is enough to know how to use such method and what is to be expected of it.

phpDocumentor and PHPStorm

Aforementioned “glance” is still needed to check what a particular method has to offer. Therefore, it’s worth mentioning, that PHPDoc’s advantages wouldn’t reveal themselves to us fully if not for its integration with the IDE environment. IDE is a software used for creating source code (text editor extended with many useful functions and tools), which, in this case, is PHPStorm. PHPStorm is able to “catalog” all the source code’s ingredients in form of a special index, which provides a basis for an autocomplete function. Thanks to this, when working on, for example, a variable containing an object, after entering a couple of first letters, we’ll receive a list of methods in this particular object’s class. Thus, looking through that class in not necessary.

In addition, PHPStorm has a built-in PHPDoc support in a form of particular options, controls, and keyboard shortcuts, which allow us to generate, complete or modify documentation for every element of the file, we’re working on. It supports operation of the index by creating additional hints based on documentation generated that way. PHPStorm also notifies you of any errors, if we “threw in” a different argument than declared into the method. All that makes developing an app quicker and more convenient in terms of mastering all these tools.

PHPDoc vs DocBlock

PHPDoc is a standard that is not only useful, but also fairly simple and intuitive, that’s why it’s an essential tool for many developers. They’re so accustomed to using it on a daily basis in heavily automated PHPStorm environment, that they often disregard using proper nomenclature describing individual elements of the documentation. In case of the team focusing mostly on proper and systematic development of the project, it can often lead to certain misunderstandings. One of such occurrences took place among our own IT team, working on developing a system for property and communication damage settlements. The dispute was rather interesting, although purely theoretical. Some members of the team claimed that the comment documenting the method is called “PHPDoc”, the rest were accustomed to calling it “DocBlock”. The truth is, both sides of the quarrel had the same thing on their mind, but force of the habit led to an intense exchange of opinions when it came to asking for “adding PHPDoc” (or, as the interlocutor preferred, “DocBlock”) or passing information about “missing PHPDoc/DocBlock”. Advocates of the “PHPDoc” argued that this is what PHPStorm usually suggests, for example in “Generate PHPDoc blocks” option (not “Generate DocBlocks”). Whereas those, who stood behind calling it “DocBlock” referred to PHPDoc specification. Ergo, it’s worth taking a closer look and clarifying the meaning of terms describing specific elements of the documentation, because the differences in meaning between them appear to be very subtle.

So, in the documentation of a single method we can distinguish 3 different ingredients or rather aspects, which, to some extent, overlap each other and are closely related, and their names are: DocComment, PHPDoc and DocBlock. If we’d like to write it manually, we should start with empty  DocComment, that means a special type of comment (underlines showed below are generated by PHPStorm, which informs about missing elements):

Now we can fill in this comment by entering a PHPDoc, that is one or more of so called tags, such as @param, @return, @throws or @property, which usually appear together with declaration of the type, name of the variable and information about individual aspects of operation of the method: what arguments does it take, what does it give back, what exceptions does it throw, what fields does it save, etc. Apart from tags, in DocComment you can also put a summary (usually a single line describing the purpose of a method) and description (our own, informal description containing notes and observations). Only a consistent comment together with PHPDoc components can be called Doc Block (a good example is the one mentioned above for the rotateImage method()). Therefore, DocBlock is a DocComment filled with content in a form of PHPDoc documentation.

As we can see, the term “PHPDoc” has at least 2 meanings and the difference between them is very subtle: one time it can be simply the content of DocBlock or a single tag, e.g. @param string $name, the other time it can mean the name of PHPDoc standard (PHP Documentation). Some people believe that “PHPDoc” is also an abbreviation of “PHPDocumentor”, and that is a wrong assumption. The question remains, is PHPDoc as in “the contents of DocBlock” only tags or is it also summary and description? Unfortunately, neither phpDocumentor documentation concluded here: https://docs.phpdoc.org/, nor documentation of the PSR-5 standard: https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md don’t specify this issue sufficiently. One can wonder if it was really necessary to introduce the term “DocBlock” when we can use “DocComment” whether it’s filled in or not. Even the name “PHPDoc” is perfectly sufficient for most of developers. However, we can suspect that there are particular situations that require such distinction, considering that DocComment is very peculiar type of comment marked differently and interpreted differently by, for example, PHPStorm – even not having any content (or maybe especially then), therefore it deserves a separate name. Although, it doesn’t matter as mush in everyday use.

As we can see, the debate regarding this issue is rather scholastic. So, how should we say: “I’m adding PHPDoc” or rather “I’m adding DocBlock”? Personally, I follow one rule I consider the closest to the PHPDoc specification: if there’s nothing documented in a file yet or it requires extensive supplementation in some places, I call it “PHPDoc completion” as in “documentation according to the standard”. If a single method isn’t documented, I suggest “adding DocBlock”. If DocComment was already added to the method, but it is empty or it doesn’t provide much information (e.g. own comments or summary) or it’s missing even a single tag, I can agree on “PHPDoc completion” – meaning one or more elements inside of DocBlock.

PHPDoc and PHP7

Version 7 of the PHP language introduced a couple of very significant changes. The best known is strict type. It means that we can (although we don’t have to – it still isn’t required) declare the type of parameters taken by the method. What’s even more interesting, we can also declare the type of data it gives back. Does it mean that PHPDoc is no longer useful? After all, we can deduce how the function works from the declaration itself. Why duplicate that information in DocBlock?

The issue is quite controversial. Some people give up on using DocBlock when they can easily acquire information they need from the method definition. It usually occurs when the definition is quite simple. They decide on introducing them only in special cases, for example, when the method uses an array of a certain type, e.g. string[].


The others claim, that it’s worth creating a complete PHPDoc documentation for every structural element. Strict type doesn’t mean that in case of using an incorrect type we’ll find out about it when the program simply stops working. PHP7 imposes the type we set by conversion, not by throwing an error, as it occurs in case of declaring an object type parameter. Thus, according to advocates of this opinion, there is a need for PHPStorm to warn us about an attempt at imposing a method with values incompatible with the ones declared.

In our project we adopted the first principle and we are using PHPDoc only when it’s really essential. We concluded that it contains multiple small methods or methods which give nothing back, so such situations are not very likely to occur, besides we can configure suitable PHPStorm messages.

In the end, it’s up to every individual team to agree on one uniform set of rules regarding PHPDoc, matching both their working style and specifics of a project they’re currently working on.

Leave a Comment

Your email address will not be published.

Facebook
LinkedIn