My opinion on documenting your code

Do not overdocument your code

In my opinion it is not very useful to extremely document your code. Your code is computer code, indeed, but write it for humans. If you write code that reads as a book then your code will be self-explanatory. A good starting principle that will save you a mass of time.

Naming stuff

Use good class names, method names and variable names. They come at no cost and are the base of a good codebase that needs less comments.

I don’t think there is much added value in writing extra documentation for the code block shown here. The method name is telling you what it does and the variables are also loud and clear. These are very small code blocks put the principle can be applied to every code part of your software.

Good :

public function calculateTotalOrderValue(Order $order){ $totalValue = $order->lines->sum('price'); return $totalValue; } public function calculateSurface($width,$height){ return $width * $height; }

Bad:

This example is an example of bad code … It does the same as the code mentioned higher, but it is totally unclear what it does without interpreting the code itself.

public function calculate($firstparam){ return $firstparam->lines->sum('price'); }

Don’t misunderstand me ?

You have to write documentation , it’s a must … But do it the good way and don’t repeat yourself. Write added value … Don’t write what your code tells you. I prefer better code above more documentation.

Write documentation for the bigger picture

Instead of documenting all methods you better learn to write self-explanatory methods. That will save you a lot of time.

It still is a good idea to document what you’re doing with a higher overview. You can explain what the total flow of the code does, so you can get the bigger picture by reading these docs.

Format your code

Code formatting makes your code more readable. Tools like PhpStorm have built-in code-formatting tools. Things like aligning key value assignments , formatting with equal spaces … makes your code more readable and comprehensible.