|
[Sponsors] |
how do you document your complicated sections of code? |
![]() |
|
LinkBack | Thread Tools | Search this Thread | Display Modes |
![]() |
![]() |
#1 |
Senior Member
Sayan Bhattacharjee
Join Date: Mar 2020
Posts: 495
Rep Power: 8 ![]() |
This might feel like a weird question, but there are some sections of code where it might be difficult for a new team member to understand what's happening.
For example, a new member might not understand why i'm splitting my double values x,y into 4 integers x1,x2,y1,y2. This is not a common thing to do, but I'm sure there are certain sections in your codebase that are quite complicated, and it becomes difficult to explain everything. https://onlinegdb.com/wfDEGbkD- Code:
#include <stdio.h> typedef struct{ int a,b; double x,y; int c; } foo; typedef struct{ int a,b; int c; double x,y; } bar; typedef struct{ int a,b; int c; int x1, x2, y1, y2; } moo; int main() { printf("sizeof(foo) : %ld\n", sizeof(foo)); printf("sizeof(bar) : %ld\n", sizeof(bar)); printf("sizeof(moo) : %ld\n", sizeof(moo)); return 0; } Code:
sizeof(foo) : 32 sizeof(bar) : 32 sizeof(moo) : 28 So, how do we actually document things in a way that's easier for new team members to understand? |
|
![]() |
![]() |
![]() |
![]() |
#2 |
Senior Member
|
Disclaimer: I have been both the last and the first developer in a project. As last I was really at level 0.
I think that you can't really assume the code you are developing is completely obscure for your fellows. For example, if you are writing a CFD code, most of the underlying theory should be written elsewhere, not in the code (but it should nonetheless be written somewhere) In your specific case, the approach you are using certainly deserves a comment but, once you write a couple of lines about it, if the underlying code doesn't have additional tricks, it is up to the person touching it to actually understand its details. For example, am I supposed to write a comment about why I need spatial search structures to perform certain geometric tasks? I don't think so, and I don't want anybody that doesn't understand that to actually touch that part of the code. Also, note that compilers have no idea of what your code does, yet they compile it and even optimize it. If you spend enough time in refactoring you will appreciate how making a code better has very little to do with knowing what the code specifically does. In general, I think anything non obvious deserves a comment at least. The obviousness of something is something that you should learn to recognize. A well commented code has, usually, at least a 10% of all lines, including spaces, dedicated to comments. But this somehow assume also that your code is also well structured, so that most parts are obvious and don't actually deserve a comment To answer your specific question, it might be wrong to target the less experienced person in the team, as they should not be even allowed to touch certain parts of the code |
|
![]() |
![]() |
![]() |
![]() |
#3 | |
Senior Member
Sayan Bhattacharjee
Join Date: Mar 2020
Posts: 495
Rep Power: 8 ![]() |
Quote:
fortran and c is simple and most importantly, easy for even the junior members to learn. even senior members, if I'm honest ... i think you told me one time that a PhD in combustion will know fortran, but they might not know c++. |
||
![]() |
![]() |
![]() |
![]() |
#4 | |
Senior Member
andy
Join Date: May 2009
Posts: 279
Rep Power: 18 ![]() |
Quote:
My personal approach is brief comments within function/subroutine bodies such as section titles, warnings, to-dos,... with anything of any length moved to the description before the function/subroutine implementation. Headers are heavily commented and form the bulk of the documentation within the code. In your example I would add a warning comment that this might cause trouble (assuming I have understood what you are doing) with a reference to the reasoning elsewhere if the location isn't implicitly understood from the adopted approach to documentation. The intended audience for comments within production or development code would be competent programmers. This may not be the case for teaching code. |
||
![]() |
![]() |
![]() |
![]() |
#5 | |
Senior Member
|
Quote:
This, however, doesn't contradict what I'm saying here. Even the most junior member has to understand the main programming tasks. You can have a separate guide for them to, say, first recognize some patterns, but in the end your code is not a coding course. |
||
![]() |
![]() |
![]() |
![]() |
#6 | |
Senior Member
Sayan Bhattacharjee
Join Date: Mar 2020
Posts: 495
Rep Power: 8 ![]() |
Quote:
in c++ one normally has to decide if they'll use templates, use getters and setters, use inheritence based organization etc. in fortran i find myself thinking more about how to improve my code, instead of thinking about which method i will use to implement the code. my previous issues with fortran were due to gfortran not being as good as ifort, and due to there not being other alternatives. but obviously things are improving. i remember arjun saying that c++ was good for extending his code easily. which is true. but i have stopped worrying about extensibility of my codes. extensibility don't exist. people rewrite their codes every year. i would rather want my codes to do one thing and to do it well. sorry for the long tirade, but coming back to fortran, my quadtree grid generator was a test for me to see if *I* was able to code in fortran. the results are great. it's very lightweight, the export functionality needs work. |
||
![]() |
![]() |
![]() |
![]() |
#7 |
Senior Member
Arjun
Join Date: Mar 2009
Location: Nurenberg, Germany
Posts: 1,282
Rep Power: 34 ![]() ![]() |
I follow what the book Code Complete ( https://en.wikipedia.org/wiki/Code_Complete ) says.
Everyone who does serious programming shall read this book. I personally DO NOT write comments in the code. Comments are distraction from the actual code and affect the readablity of the code. The code shall be comment : That means one shall write the code such a way that it shall be obvious to the reader what is written. For example lets say i do iteration on model then my function would be something like: Code:
void iterate() { applyBoundaryCondition (); calculateGradients (); descretize (); solveLinearSystem (); exchangeVariablesAtHaloCells(); } In this example, there is no need to write comments. Its obvious: I also make sure that I do not do Smarty Pants coding to show that how great programmer I am. I keep the code simple as possible. The only time I comment in the code is where things are not obvious and something out of ordinary happening. Then I add explanation as much as possible. So reader in wildkatze knows that if there is a comment there he shall pay attention. (it would be lost in sea of comments). PS: the example of code that is commented in Wildkatze is Third Order Gradients. This is where efficiency is gained by clever strategy and approach. Need to mention to the reader what is been done and why it is done. Things are not obvious so expanation was needed. |
|
![]() |
![]() |
![]() |
![]() |
#8 |
Senior Member
|
One general rule of thumb that, in practice, I've found myself adopting (without actually designing it to be in this way) is that whenever I need pen and paper to figure things out then the thing probably deserves a comment.
|
|
![]() |
![]() |
![]() |
|
|
![]() |
||||
Thread | Thread Starter | Forum | Replies | Last Post |
How to make CFD code architechture flexible enough for future modifications? | aerosayan | Main CFD Forum | 6 | September 3, 2021 04:35 |
Fortran->Assembly : How to remove redundant non-vectorized code? | aerosayan | Main CFD Forum | 6 | November 20, 2020 05:37 |
The FOAM Documentation Project - SHUT-DOWN | holger_marschall | OpenFOAM | 242 | March 7, 2013 12:30 |
Small 3-D code | Zdravko Stojanovic | Main CFD Forum | 2 | July 19, 2010 10:11 |
Design Integration with CFD? | John C. Chien | Main CFD Forum | 19 | May 17, 2001 15:56 |