tum-esi / common-coding-conventions Goto Github PK
View Code? Open in Web Editor NEWA concise and universal guide to clear software design.
A concise and universal guide to clear software design.
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.
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.
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.