undefined | Better HN

0 pointsorneryostrich6y ago0 comments

Keldon Jones’ Race for the Galaxy AI is brilliant. Every line is documented C. It trains and deploys a neural net. It has a fast and functional GUI. Most diehard RftG players have cut their teeth by losing to Keldon a few dozen times before really learning the game.

Keldon was contracted a few years later to develop the RftG apps on iOS and Android, which are easily worth $4.

Source: https://github.com/bnordli/rftg

Precompiled binaries: http://keldon.net/rftg/

0 comments

taspeotis6y ago

> Every line is documented C

Every line? Oh dear [1]:

    /* Set verbose flag */
    verbose++;
    ...
    /* Set advanced flag */
    advanced = 1;
    ...
    /* Set expansion level */
    expansion = atoi(argv[++i]);
    ...
    /* Initialize game */
    init_game(&my_game);

I assume the verbose flag is incremented because there's multiple levels of verbosity, whereas the advanced flag is a boolean, and i is incremented because expansion is not a command line flag (rather, an option). But I wouldn't know that from the comments! Especially useful to know if like, verbosity actually has multiple levels, like -v and -v -v or -v -v -v and so on ... instead of knowing that init_game is ... init'ing the game.

Compare all those comments to this [2], which is actually a spectacularly useful comment.

Signal to noise ratio!

[1] https://github.com/bnordli/rftg/blob/master/src/learner.c

[2] https://github.com/bnordli/rftg/blob/master/src/replay.c#L94

kstrauser6y ago

Yikes, I've gotta agree:

    /* Exit */
    exit(1);

Well, yes, I see that. It might have been helpful to extend that to "Exit with an error status", perhaps, but as-is it tells you literally nothing that the code doesn't.

teknopaul6y ago

IMHO Coding guides should ban "SBO comments" Statin the Bleedin Obvious. Let devs decide what SBO is, usually its bleedin obvious.

dror6y ago

Actually, this line:

/* Set expansion level */

    expansion = atoi(argv[++i]);

Is an example of ugly code. They're doing multiple things in one line, and in a confusing order.

# Increment i by 1.

# Grab the command line argument in position i

# Convert from string to integer.

# Assign to the variable expansion.

Note that there's no error checking to handle strings that don't convert to ints.

Arguably, any serious C developer can read this on the fly, but I seriously object to code with side-effects like the above ++i. It's often confusing to read and change.

I'm not criticizing the original author, more nit-picking on this as an example of great code.

GuB-426y ago

I don't have a problem with that code. It is idiomatic C code, like *p++ or flag &= ~mask. ++i is a bit less common than i++ but nothing unusual. The lack of of error checking is more concerning though. It can be justified though, and it brings me to the next point.

The comment is the worst part. It is useless, it literally repeats the most obvious part of the code. A good comment would be something like "there is no error checking because arguments are already validated in the GUI, also 0 is an acceptable default".

For me, comments should not repeat what the code is doing. Comments are for expressing what is in the the mind of the developer that cannot be expressed in code. Example : "constant found using empirical testing", "Hermite spline formula" or "required on Windows". (Edit: the Hermite spline example is actually a bad one, a better idea would be to write a function called hermite_spline_formula instead)

If some coding rule require you to comment, find something to say about your code that isn't your code. It will also help you think more about what you just wrote.

2 more replies

prasanthmj6y ago

It seems to follow the notion that more comments = better code. If the symbol names are explanatory enough, the code itself will be self-explanatory. Then all that must be commented about will be special cases handled/not handled and why a certain decision is taken about handling in a certain way.

Often, "every single line is commented" results from blindly following a certain "Standard" that demands that. Eventually generating meaningless comments all over the code. Then the important points never gets mentioned in the comments or just gets buried in the noise.

j / k navigate · click thread line to collapse