What points and rules should be considered and followed when writing program code? What methods and approaches can be used to improve code quality despite, or perhaps because of, growing team sizes and increasing project complexity?
A good approach is to establish programming guidelines that specify requirements for code and code commenting. If the guidelines are followed, the result is code that is "cast from a single mold." Figuratively speaking, a "uniform language" is agreed upon, according to whose conventions the code is created. Code passes through many hands during development, so the guidelines should be interpreted and written strictly and comprehensively to prevent time being lost due to poorly understood code. Furthermore, the guidelines and their adherence to them establish a certain quality standard within the company, ensuring that no uncommented program sections or those littered with jump instructions (goto) make it into the review process or, in the worst case, into the finished product. The programming instructions cover all parts of the software. They range from file names and the type of documentation to specifications for variable names.
When considering what information the instructions should contain, I consider the following guidelines to be useful. For a structured approach, an initial division into Source code and Comments In the source code, the specifications functionallearner or formulalearner Be nature.
|
|
| Dipl.-Ing. Goran Madzar, Partner, Senior Systems Engineer E-mail: madzar@medtech-ingenieur.de Phone: +49 9131 691 240 |
|
Do you need support with the development of your medical device? We're happy to help! MEDtech Ingenieur GmbH offers hardware development, software development, systems engineering, mechanical development, and consulting services from a single source. Contact us. |
|
At Comments The language, minimal content, and positioning are specified. An example of this is: Every function must be commented. This comment must contain a brief function description and describe all passed parameters. The use of a tool can also be specified during commenting. Doxygen is a very good and free tool that generates printable documentation of the program code from the keywords used in comments.
Functional specifications for the source code include requirements for functions, data types, and operators. Certain functions that make the code difficult to read should be prohibited (goto(), complicated constructs with decrements and increments). Furthermore, it is worthwhile to restrict the data types to be used. For example, the use of data types from stdint.h the size and value range independent of the target system.
Both formal specifications for the source code This concerns the external appearance. This defines requirements such as indentation with spaces instead of tabs, bracketing of functions, and the naming of constants, variables, functions, and other attributes. Using the module/class name as the function prefix makes it much easier to assign functions to modules.
Extensively commented and "clean" code is easier to reuse, hand over to another programmer, and maintain. Because a function whose task is precisely known and whose required parameters are described is easy to understand and therefore use.
And in general, I can say: As a programmer, it makes me proud when I have written a nice piece of code and receive a compliment for it during a review or from the customer ;)
One challenging aspect, of course, is the length of the guidelines. The guidelines I created are 30 pages long. It's also a good idea to create a summary that doesn't exceed one page (DIN A4). This summary can serve as a compact reminder at work. The summary is shown in the image below and can be downloaded as a PDF. Anyone interested in the complete guideline can simply contact me.
Programming guidelines overview as PDF for download
What are your thoughts on the topic of programming guidelines? Are they necessary? What experience do you have with this topic? Where do you see the problems or weaknesses in their creation and implementation in companies? I would be very happy to hear from you, of course, even if you have any criticism, suggestions, or questions on the topic. Anyone interested in the complete guideline can simply contact me.
Best regards
Benjamin Eichinger