tum-esi / common-coding-conventions Goto Github PK

It was mentioned that "Functions that appear in the header file are public, while functions that only appear in the .c files are private.".
I think this is violating, in somehow, the idea behind the header file. The header file should include the signature of ALL functions. Do you have this recommendation written somewhere?

There is the mention of having TODO: in the comments but it can be even made better via the use of helpers around them. One example for VS Code that highlights them in the editor but also in the scrollbar to easily find them.

VS Marketplace Link: https://open-vsx.org/vscode/item?itemName=wayou.vscode-todo-highlight

There are two things missing about dependencies in my opinion.

1. How to tell a user how to install them: This depends on the language but python has this requirements.txt and setup.py convention. Poetry is a new way to manage them, I don't have much experience but for me that is finally the direction for python dependency management. (https://python-poetry.org/). In JS, package.json existed for a long time and manages this in an OK way. In any case, so many sw packages on GitHub repositories list the dependencies in the Readme.md in a textual way but it is always better to provide a simple way for the user. The above-mentioned methods also assure version management, giving you more hopes that the user will not install a dependency that is not the right version you need.

2. How to manage the dependencies as the developer: So using another package that satisfies your need is not necessarily a bad thing to do. If you are using one, you have to manage it and its version. Thus, you should definitely note the version you are using (ideally in a dependency management convention). In addition, we might be able to give tips on whether to add them or not. Reminding developers that a dependency also has its own dependencies and you can end up in a software package where you have more than 100 resolved dependencies. So encouraging people to no use dependencies for simple things is good in my opinion.

The individual chapters list more rules than the ones shown in the main summary. Should the chapters repeat the important rules that are already covered in the summary?

Pro: chapters will be standalone and more complete
Con: redundant content: maybe boring, extra effort to synchronize

Code sample on Github Pages (https://tum-esi.github.io/common-coding-conventions/)

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.