Mentioning Commenting standards

[egekorkan]

Not sure about Python but in Javascript, there is this pseudo-standard called JSDoc that visual studio code recognizes by default. It is simply about putting comments like this before the function:

/**
 * Solves equations of the form a * x = b
 * @example
 * // returns 2
 * globalNS.method1(5, 10);
 * @example
 * // returns 3
 * globalNS.method(5, 15);
 * @returns {Number} Returns the value of x for the equation.
 */
globalNS.method1 = function (a, b) {
    return b / a;
};

It can be used to generate documentation etc but the nicest use case for me is when reviewing code. VS-Code shows a rendered version of these comments when you hover your mouse pointer on the use of this function somewhere in the code. Below is an example screenshot:

So if people use such standards, it makes it easier for others to contribute.

[emareg]

This is mentioned as Docstrings on the details page for documentation: https://github.com/tum-esi/software-design-guide/blob/master/chapter/5_documentation.md

Do you think it makes sense for smaller projects? I mainly see this for larger frameworks where a full documentation is useful.

[egekorkan]

Well mostly people write some comment for the function anyways, so if they do it in a "standardized" way, it helps people. For me, they are sort of a must for any project I need to switch between files or scroll one big long file with many functions.