News for hackers. Stuff that matters.
Re:Elevate your C programming skills by exploring the SQLite... by ivanbakel on Sunday July 09, 2017 @08:32AM (#14729437)
The first example made my skin crawl. No spacing between related blocks of code, no indentation of conditional statements to help pick them out against the background, and since when is a lack of comments in the body of a method a good thing?
Re:Elevate your C programming skills by exploring the SQLite... by w4rh4wk5 on Sunday July 09, 2017 @08:56AM (#14729534)
I fully agree with you. Here is how I'd write the first example. Note that I don't know anything about SQLite and that I may have introduced typos. The comments 'resize ...' are just place holders.

https://gist.github.com/W4RH4WK/57a8701190b682bcac5b8daadb43...

Re:Elevate your C programming skills by exploring the SQLite... by kyberias on Sunday July 09, 2017 @09:30AM (#14729639)
I like your formatting of the code, but...

You introduce comments that are basically just noise. The name of the method already states what it does. The rest is just very simple details, actually memcpy's. Most of the comments are totally unnecessary.

Code comments are not pure good, they are not Schindler's List. They are necessary evil. Every time you need to add a code comment you have failed to write clean code that it easy to understand.

Every comment that you add has a cost. Someone needs to read it _in_addition_ to the code that it tries to describe. The code itself either is correct or isn't. The comment cannot fix that. But it can slow down the reader to understand what the code does. Whether there is a comment or not, the reader still needs to read the code.

Re:Elevate your C programming skills by exploring the SQLite... by w4rh4wk5 on Sunday July 09, 2017 @11:29AM (#14730149)
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.

Re:Elevate your C programming skills by exploring the SQLite... by kyberias on Sunday July 09, 2017 @02:23PM (#14730973)
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.

Re:Elevate your C programming skills by exploring the SQLite... by w4rh4wk5 on Sunday July 09, 2017 @03:58PM (#14731369)
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.
Re:Elevate your C programming skills by exploring the SQLite... by noir_lord on Sunday July 09, 2017 @10:22AM (#14729845)
Comments are salt, just enough enhances, too much spoils.

I'll take a codebase with no comments over pages of

    // assign 10 to a
    a = 10;
particularly when why you are assigning 10 would actually be a (more) useful comment.
Re:Elevate your C programming skills by exploring the SQLite... by w4rh4wk5 on Sunday July 09, 2017 @11:30AM (#14730156)
I support the statement that comments should explain why something is done and not how something is done, in general. See my other reply why I chose to do it like this.
Re:Elevate your C programming skills by exploring the SQLite... by eru on Sunday July 09, 2017 @04:16PM (#14731466)
> Every time you need to add a code comment you have failed to write clean code that it easy to understand.

As far as possible the code should tell you 'what' it is doing. But pure code alone has a hard time telling you 'why' it does what it does, and an even harder time telling 'why not'?

(Ie 'Why are we using this complicated approach, and not a simpler one?', 'Why can we get away with this simple approach, why don't we have to worry about corner case x?')

Re:Elevate your C programming skills by exploring the SQLite... by tzs on Sunday July 09, 2017 @01:57PM (#14730873)
What we used to do when I worked at a consulting firm that took contracts whose deliverables included source code is when writing code just put in the comments that we needed for ourselves during development.

For the final delivery of source code we'd make a binder that had a code listing on the pages that were on the right side, with a detailed running commentary on the pages that were on the left. On the left hand pages we could go into great detail (we'd add vertical space on the right hand pages as needed to keep things lined up).

The left hand pages in essence were almost a book on how to do whatever it was the code was doing, making it easy for the client to hand over the project to their own programmers after we were gone. We did not rush writing the left hand pages. Sometimes I spent more time writing the left hand pages than I had spend writing and debugging the code. (Our contracts were all fixed bid contracts, so spending all that time didn't raise the price for the client).

Re:Elevate your C programming skills by exploring the SQLite... by sidlls on Sunday July 09, 2017 @11:54AM (#14730312)
> Every time you need to add a code comment you have failed to write clean code that it easy to understand.

I find this to be a rather curious statement. I don't believe "clean code" and "easy to understand" are necessarily related as strictly as you seem to.

Sometimes solutions to problems are messy and difficult to reason through with just the text of the solution ("code"). Code comments that elucidate meaning when the solution is thorny make code clean. The absence of comments might make code pure (in some sense), but not clean.

Re:Elevate your C programming skills by exploring the SQLite... by kyberias on Sunday July 09, 2017 @02:17PM (#14730943)
>> Every time you need to add a code comment you have failed to write clean code that it easy to understand. > I find this to be a rather curious statement. I don't believe "clean code" and "easy to understand" are necessarily related as strictly as you seem to.

Well, if we select a definition for clean code to be what Robert C. Martin defines in his book "Clean Code", it very much is related to code that is maintainable, that is readable (i.e. easy to understand). I'm not saying they are "strictly" related as you seem to suggest I think.

The absence of comments is not a necessary property of clean code. But the absence of unnecessary comments is. Most comments are unnecessary.

Also, most importantly, the presence of comments is not a sufficient criteria for clean code. Code can be of very high quality without any comments.

You seem to say that _good_ comments may improve the quality of code and I agree.

Re:Elevate your C programming skills by exploring the SQLite... by zbuf on Sunday July 09, 2017 @09:20AM (#14729601)
This is a nice example.

It's not that we are not capable of understanding the original code block, but the 'breathing space' and just some minor sparse comments now allow much of that understanding in less than a few seconds -- a real practical side when working on a large body of code.

And it does that without interfering with the 'good practices' highlighted in the article.

Re:Elevate your C programming skills by exploring the SQLite... by logicallee on Sunday July 09, 2017 @09:32AM (#14729652)
One of the most influential few paragraphs I've ever read in my life was this FAQ entry:

https://sqlite.org/faq.html#q17

It must not be left out of any discussions of style in the SQlite codebase.

Without this approach, many stylistic choices would not be nearly as acceptable.

(But one thing I never looked into: do the developers use a more readable, better-commented and -spaced style, fewer tricks that produce fewer warnings, to write their test suites?

Or are they written in the same style?)

Re:Elevate your C programming skills by exploring the SQLite... by Joky on Sunday July 09, 2017 @01:40PM (#14730791)
Testing in sqlite is great! That still isn't a reason to write unreadable code though. It may just be a "Linux Torvald" kind of approach: if you can't read the code as is we don't want you in the community.
Re:Elevate your C programming skills by exploring the SQLite... by logicallee on Sunday July 09, 2017 @03:26PM (#14731243)
Do you know the answer to my question? Is the testing code (which I can only assume is not itself tested) is written in the same style and way as the code it is testing? Or is it written in a different style?
Re:Elevate your C programming skills by exploring the SQLite... by zakk on Sunday July 09, 2017 @08:41AM (#14729473)
> since when is a lack of comments in the body of a method a good thing?

I think that's the rationale: you are supposed to explain what you do, not how you do it. The function is short enough that a global comment is enough.

I agree with you, that a couple of comments in the function body wouldn't have hurt.

Re:Elevate your C programming skills by exploring the SQLite... by zbuf on Sunday July 09, 2017 @09:26AM (#14729625)
To be fair to the article, it 'remarks' on the lack of comments there but doesn't specifically call it out as a best practice.
Re:Elevate your C programming skills by exploring the SQLite... by userbinator on Sunday July 09, 2017 @12:12PM (#14730417)
I actually found it a welcome and refreshing change from the excessively verbose and spread-out style that seems to have become popular these days (of which Java and C# are the main examples.)

I'm not sure all the casts are necessary, however, and I'd probably reduce usage of some sizeofs just using the constant (sizeof(i16) should obviously be 2, if the name is any indication.)

Re:Elevate your C programming skills by exploring the SQLite... by kardos on Sunday July 09, 2017 @12:29PM (#14730503)
> I'd probably reduce usage of some sizeofs just using the constant

Why? The sizeof is resolved into a constant at compile time, ie, no runtime cost. I see the 'sizeof(i16)' as conveying more information than a '2'.

Re:Elevate your C programming skills by exploring the SQLite... by aleksei on Sunday July 09, 2017 @12:29PM (#14730504)
i16 seems to be a typedef for short int, which may be actually be larger than 2 bytes depending on the compiler.
Re:Elevate your C programming skills by exploring the SQLite... by minipci1321 on Sunday July 09, 2017 @01:45PM (#14730817)
Even more so:

-- the fact that the code didn't use the int16_t from stddef.h but rather defined their own, could hint in the sense that a signed-int-over-exactly-16-bits might be unavailable in the ABI. People defining their own exact-width integral types (instead of pulling in stddef.h), rarely think about how that makes the code harder to interpret for a reader.

Now, if the type i16 might indeed be wider than 16 bits, sizeof becomes perfectly justified but '16' is not.

Re:Elevate your C programming skills by exploring the SQLite... by ivanbakel on Sunday July 09, 2017 @01:47PM (#14730824)
If it's specified as i16, it would be exactly two bytes in all situations - there would be no logic in including a size parameter that didn't actually mean anything, and sized ints are specifically meant to be platform-independent.
Re:Elevate your C programming skills by exploring the SQLite... by makapuf on Sunday July 09, 2017 @03:39PM (#14731296)
But then why not use stdint ?
Re:Elevate your C programming skills by exploring the SQLite... by __s on Sunday July 09, 2017 @09:39AM (#14729675)
Here, have a window manager I wrote, maybe it'll make your skin crawl right off: https://github.com/serprex/nobox/blob/master/nobox.c
Re:Elevate your C programming skills by exploring the SQLite... by marvy on Sunday July 09, 2017 @11:23AM (#14730123)
That is COMPACT. I always thought that a window manager was supposed to be big. This fits in one file!

(A note on code style though: some of your lines are a bit too long. Have pity on those with small screens. Seriously, it's not that hard to break up line 94.)

Where can I learn enough about X to read this code?

Re:Elevate your C programming skills by exploring the SQLite... by __s on Sunday July 09, 2017 @09:42PM (#14732816)
I'd suggest reading the dwm source: http://git.suckless.org/dwm/tree/dwm.c

It's still one file, but it has more features & is less obfuscated

Otherwise I mostly learnt by reading XCB header files

That said things are going the way of Wayland, so I've since switched: https://github.com/serprex/noway

Re:Elevate your C programming skills by exploring the SQLite... by marvy on Monday July 10, 2017 @11:54PM (#14741465)
Thanks! Though I'd rather read yours. A couple of hundred lines seems less intimidating than a couple of thousand. Though still I doubt I'll get around to it.
Re:Elevate your C programming skills by exploring the SQLite... by WalterGR on Sunday July 09, 2017 @04:59PM (#14731632)
Have pity on those with small screens.

How small are your screen(s)? What resolution do you run them at? What size font? Do you have eyesight issues?

I have decent vision at monitor distance. On a 13-inch Macbook Pro, using a font of reasonable size, I can easily diff two files with a line length of 108 - side-by-side.

I'm curious, then, why others can't do that. (Eyesight issues aside, of course.)

(Whether code lines should be 108 characters long is a separate issue.)

Re:Elevate your C programming skills by exploring the SQLite... by marvy on Sunday July 09, 2017 @08:36PM (#14732589)
At home, my desktop has a resolution of 1366x768. (I usually use my laptop, which is higher than that, but whatever.) At work, I have monitors in the "portrait" position, so I only have 1080 horizontal pixels unless I'm willing to split something across two screens. (Never!)

But in this case, all that is not relevant. The link was to Github, and Github enforces a width of less than a thousand pixels, regardless of screen size.

Re:Elevate your C programming skills by exploring the SQLite... by WalterGR on Sunday July 09, 2017 @11:51PM (#14733269)
I have monitors in the "portrait" position

Excellent, thanks. That's something I hadn't considered.

But in this case, all that is not relevant. The link was to Github, and Github enforces...

Ah. I assumed you were speaking generally.

Re:Elevate your C programming skills by exploring the SQLite... by marvy on Monday July 10, 2017 @07:50AM (#14735068)
Well, I mostly was. Long lines are _generally_ inconvenient. Everything from portrait screens to websites that won't use the full screen width to someone who wants to a printout of the code for some reason (even printing in landscape is not enough).
Re:Elevate your C programming skills by exploring the SQLite... by NicoJuicy on Sunday July 09, 2017 @12:21PM (#14730458)
You should read 'Clean Code', comments mean a failure of clean understanding code
Re:Elevate your C programming skills by exploring the SQLite... by renox on Sunday July 09, 2017 @04:26PM (#14731505)
And you should avoid this kind of strong assertion: there are many cases where comment are useful.. To fix a bug, I replaced a binary serialiser by a text serialiser, how could the code explain this? Also with threading, comments are often useful.
Re:Elevate your C programming skills by exploring the SQLite... by NicoJuicy on Sunday July 09, 2017 @05:11PM (#14731682)
In c# , an obsolete attribute on the binaryserialiser, in the same namespace as the text serializer. With the reason why you switched and why it's obsolete now

Perhaps should have added a 'mostly' in my original reply though. But I want to keep comments always to a minimum

Re:Elevate your C programming skills by exploring the SQLite... by kyberias on Sunday July 09, 2017 @09:26AM (#14729624)
That code doesn't seem to require any comments. Code comments are usually a smell. The author couldn't write code that's easy to understand so he had to write a comment to describe it.
Re:Elevate your C programming skills by exploring the SQLite... by cocoa19 on Sunday July 09, 2017 @09:44AM (#14729693)
I second this. For more info about why usually code comments are a code smell, I recommend reading the Clean Code book (Robert Martin), the chapter on Comments.
Re:Elevate your C programming skills by exploring the SQLite... by rossy on Sunday July 09, 2017 @10:22AM (#14729840)
I've worked with people who believe this, including at least one devout follower of Clean Code and I totally disagree. One developer's obvious self-documenting code is another developer's WTF. Yeah, some projects have a lot of code that doesn't need to be commented, especially web and GUI projects that have a lot of similar code for performing CRUD operations on various database objects. That shouldn't make you get out of the habit of commenting things that actually need to be commented.

One major WTF in this code that stood out for me is the place where char zExtra is cast to const char * * . (Pointer-to-pointer casts should be alarming for any C programmer.) Only later, I realised that zExtra was a block of memory containing three arrays of different type. There should at least be a brief comment explaining the memory format of zExtra, and maybe one explaining why the code makes a single allocation instead of three separate allocations (is it performance critical?)

Re:Elevate your C programming skills by exploring the SQLite... by kyberias on Sunday July 09, 2017 @02:07PM (#14730900)
I don't believe you _totally_ disagree. You must understand that littering every single like of code with comments describing minute details is unnecessary. There must be a balance.

I'm not a purist by any means. I don't think comments are pure evil either. They have their uses but to say that code without comments is

Clean Code principles only state that code comments are not good _per se_. Most comments are just noise. Yet they are sometimes needed and bring value. It's not black and white.