[aerosayan]

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-

#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 :

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?

[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]

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++.

[andy_]

Originally Posted by aerosayan

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]

Originally Posted by aerosayan

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]

Originally Posted by sbaffini

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.

[arjun]

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:

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]

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.