4 ms·

Of course you can omit the comments in the body of the function. Yet I do not think they are "just noise". In my point of view they help with two things when go

Of course you can omit the comments in the body of the function. Yet I do not think they are "just noise". In my point of view they help with two things when going over the code: First they reduce the cognitive load, second they help maintaining a red thread throughout the code. Let me explain that in more detail: while `malloc((sizeof(char) + sizeof(i16) + 1) N)` tells me how big the buffer is, it does not tell how it is organized / how it will be used. Of course you could introduce a struct for this but that would get out of hand quickly. Having the comment one line prior illustrating the layout helps one to understand what comes next. Hence offsetting `zExtra` after each `memcpy` part becomes obvious. `resize azColl` (and similar) serves as a heading for the following block, allowing one to easily find a specific step in a list of multiple steps. Scaning the whole function with your eyes for such headings is much faster than parsing for `pIdx->azColl` inside a call to `memcpy`. In the end, whether to put these kinds of comments into the code-base or not should be part of the coding convention chosen for the project. People have different opinions and after all it is a trade-off. The way I did it in this example is the way I'd do it in a big (community driven) code base like SQLite. If the convention would state otherwise, I wouldn't add them.

kyberias 9y ago
Have you considered that you can structure your code with something else than "header comments"? For example, if you find that you need to split a function into multiple steps and you end up adding "header comments", you could also split that code into subroutines and name those functions accordingly? Also, I usually find that just adding one or two line feeds between code blocks helps to add enough structure.
- w4rh4wk5 9y ago
  I often consider that in languages like Python or Haskell. There you can easily do this in very few lines of code and with limited scope (inner function, Haskell's where). In C this is often too much overhead in my opinion.

kyberias 9y ago

Have you considered that you can structure your code with something else than "header comments"? For example, if you find that you need to split a function into multiple steps and you end up adding "header comments", you could also split that code into subroutines and name those functions accordingly? Also, I usually find that just adding one or two line feeds between code blocks helps to add enough structure.

w4rh4wk5 9y ago
I often consider that in languages like Python or Haskell. There you can easily do this in very few lines of code and with limited scope (inner function, Haskell's where). In C this is often too much overhead in my opinion.