CFD Online Logo CFD Online URL
www.cfd-online.com
[Sponsors]
Home > Forums > General Forums > Main CFD Forum

how do you document your complicated sections of code?

Register Blogs Members List Search Today's Posts Mark Forums Read

Like Tree8Likes
  • 1 Post By sbaffini
  • 2 Post By andy_
  • 1 Post By sbaffini
  • 1 Post By aerosayan
  • 2 Post By arjun
  • 1 Post By sbaffini

Reply
 
LinkBack Thread Tools Search this Thread Display Modes
Old   February 13, 2022, 10:22
Default how do you document your complicated sections of code?
  #1
Senior Member
 
Sayan Bhattacharjee
Join Date: Mar 2020
Posts: 495
Rep Power: 7
aerosayan is on a distinguished road
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;
}
OUTPUT :
Code:
sizeof(foo) : 32
sizeof(bar) : 32
sizeof(moo) : 28
As shown by the results above, the structs consume different amounts of memory, and for performance critical codes, everything matters. If someone doesn't understand the memory layout, they won't be able to contribute to the project. And I don't know the experience level of the persons who might be in my team, I don't know how much documentation they'll need.

So, how do we actually document things in a way that's easier for new team members to understand?
aerosayan is offline   Reply With Quote

Old   February 13, 2022, 11:45
Default
  #2
Senior Member
 
sbaffini's Avatar
 
Paolo Lampitella
Join Date: Mar 2009
Location: Italy
Posts: 2,146
Blog Entries: 29
Rep Power: 38
sbaffini will become famous soon enoughsbaffini will become famous soon enough
Send a message via Skype™ to sbaffini
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
aerosayan likes this.
sbaffini is offline   Reply With Quote

Old   February 13, 2022, 12:14
Default
  #3
Senior Member
 
Sayan Bhattacharjee
Join Date: Mar 2020
Posts: 495
Rep Power: 7
aerosayan is on a distinguished road
Quote:
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
Thanks for your answer. You're right. I'm currently using fortran instead of c++ because my junior team members 10 years down the road won't be able to understand complicated c++ easily.

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++.
aerosayan is offline   Reply With Quote

Old   February 13, 2022, 13:45
Default
  #4
Senior Member
 
andy
Join Date: May 2009
Posts: 263
Rep Power: 17
andy_ is on a distinguished road
Quote:
Originally Posted by aerosayan View Post
So, how do we actually document things in a way that's easier for new team members to understand?
Within a group one should follow how the group handles documentation.

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.
sbaffini and aerosayan like this.
andy_ is offline   Reply With Quote

Old   February 13, 2022, 13:49
Default
  #5
Senior Member
 
sbaffini's Avatar
 
Paolo Lampitella
Join Date: Mar 2009
Location: Italy
Posts: 2,146
Blog Entries: 29
Rep Power: 38
sbaffini will become famous soon enoughsbaffini will become famous soon enough
Send a message via Skype™ to sbaffini
Quote:
Originally Posted by aerosayan View Post
Thanks for your answer. You're right. I'm currently using fortran instead of c++ because my junior team members 10 years down the road won't be able to understand complicated c++ easily.

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++.
Yes, exactly. Not that I have direct experience with someone in particular, but the idea is that Fortran has anything happening under the sun and is as easy as scientific low level programming can be, in my opinion.

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.
aerosayan likes this.
sbaffini is offline   Reply With Quote

Old   February 13, 2022, 22:00
Default
  #6
Senior Member
 
Sayan Bhattacharjee
Join Date: Mar 2020
Posts: 495
Rep Power: 7
aerosayan is on a distinguished road
Quote:
Originally Posted by sbaffini View Post
Yes, exactly. Not that I have direct experience with someone in particular, but the idea is that Fortran has anything happening under the sun and is as easy as scientific low level programming can be, in my opinion.

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.
yes, additionally, i also realized that i don't find myself wasting my time in fortran.

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.
Attached Images
File Type: png qtree-1.png (18.4 KB, 10 views)
sbaffini likes this.
aerosayan is offline   Reply With Quote

Old   February 14, 2022, 01:52
Default
  #7
Senior Member
 
Arjun
Join Date: Mar 2009
Location: Nurenberg, Germany
Posts: 1,271
Rep Power: 33
arjun will become famous soon enougharjun will become famous soon enough
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.
sbaffini and aerosayan like this.
arjun is offline   Reply With Quote

Old   February 14, 2022, 04:40
Default
  #8
Senior Member
 
sbaffini's Avatar
 
Paolo Lampitella
Join Date: Mar 2009
Location: Italy
Posts: 2,146
Blog Entries: 29
Rep Power: 38
sbaffini will become famous soon enoughsbaffini will become famous soon enough
Send a message via Skype™ to sbaffini
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.
aerosayan likes this.
sbaffini is offline   Reply With Quote

Reply

Thread Tools Search this Thread
Search this Thread:

Advanced Search
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are Off
Pingbacks are On
Refbacks are On


Similar Threads
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 05:35
Fortran->Assembly : How to remove redundant non-vectorized code? aerosayan Main CFD Forum 6 November 20, 2020 06:37
The FOAM Documentation Project - SHUT-DOWN holger_marschall OpenFOAM 242 March 7, 2013 13:30
Small 3-D code Zdravko Stojanovic Main CFD Forum 2 July 19, 2010 11:11
Design Integration with CFD? John C. Chien Main CFD Forum 19 May 17, 2001 16:56


All times are GMT -4. The time now is 22:40.