If you want to see actual code that flew to the Moon: https://github.com/chrislgarry/Apollo-11
My favorite part from that: https://github.com/chrislgarry/Apollo-11/blob/27e2acf88a6345...
Please do not attempt to simplify this code
71–80 of 647 posts
Re: Please do not attempt to simplify this code
#72The comment:code ratio is higher than anything I write or that I’ve seen. However, it does give me some comfort. When it’s not gamed, do other HNers also feel that a high comment:code ratio probably indicates quality? There are reasons why this may be the case. (More thought, more time and a large team etc) I don’t advocate using this measure to reward anyone because it would be gamed immediately.
I think it's usually a sign of a poorly understood domain or a poorly modeled problem. It's not a good sign; it's not necessarily a bad sign; it's (at best) an admission of one's limitations.
Comments become useful when behavior is implicitly tricky. Ideally you'd make the "trickiness" tangible and expressible in-whatever-language you're in, but that's not always easy to do.
Re: Please do not attempt to simplify this code
#73The comment:code ratio is higher than anything I write or that I’ve seen. However, it does give me some comfort. When it’s not gamed, do other HNers also feel that a high comment:code ratio probably indicates quality? There are reasons why this may be the case. (More thought, more time and a large team etc) I don’t advocate using this measure to reward anyone because it would be gamed immediately.
I generally find that a high comment to code ratio, if the comments are of the form "Do this thing because of this reason", indicates quality. It indicates the programmer both knows what they wrote and why they wrote it, and it helps future maintainers figure out under what circumstances the code can be changed, refactored, or removed and under what circumstances the original behavior must be kept.
A high comment to code ratio, where the comments are of the form "Do this thing in this way," indicates a lack of quality - generally a sign that the programmer is not confident enough in the language that they're writing in, and is trying to solve language-level problems instead of business-level problems.
Uncommented code better come with some reference for why the code exists in the form it does. Sometimes commit logs and the VCS "annotate"/"blame" feature works. Sometimes commit logs link to bug trackers or feature requests. Sometimes there's a README. If you don't have any of those, I tend to find that it's generally low-quality code.
Our purpose is to deliver business value. (Or non-business value, as the case may be; if you're writing a free video game for fun, you want people to successfully have fun.) Our purpose is not to generate lines of code. All code is, to some extent, legacy code; comments can help it be manageable legacy code, or make it even more unmanageable.
Re: Please do not attempt to simplify this code
#74Earlier quoted context omitted.
I actually would say it’s almost the opposite, if you’re writing clean, expressive code it shouldn’t need explaining. And if your code is clean, you shouldn’t have a bunch of redundant comments explaining the obvious.
I'm not sure there are many cases where there should be long amounts of expressive code. If you're doing something obvious, you should generally be able to program it concisely, in which case you have a high comment-to-code ratio because the amount of code is low. Sometimes this will be because you're importing an external library to do something, or because you're calling out to an internal library. Sometimes this w…
I might have misused the word expressive, I don't mean bloated code with more than necessary logic.
I just meant simple to understand variable, function, and class names. That combined with small classes and functions, makes following the logic of your program extremely easy.
Following concepts like DRY (don't repeat yourself) and the single responsibility principle ensure that you're making more easily testable code, and I'm sure less overall LOC.
Re: Please do not attempt to simplify this code
#75This code would probably a lot shorter if every function call was not followed by a ‘if err != nil’ statement. This reminds me of Win32 programming.
Re: Please do not attempt to simplify this code
#76"it became clear that we needed to ensure that every single condition was handled and accounted for in the code" This is a feature of several (mostly functional) programming languages, e.g. Haskell. Fun to see that often people figure out that these types of concepts are a smart way to write your code. Too bad it usually means many people reinvent the wheel instead of learning about computer science history and other…
I know a business coach who regularly asks his audience "Who here makes better burgers than McDonalds?". When half the audience raises their hand, he asks them why they don't outsell this giant company. Functional programming advocats, especially for the "pure" ones like Haskell, always strike me as odd. It seems that all the beauty of those languages make people obsess over that beauty and purity while keeping them…
The most useful product in Haskell for me personally is pandoc the universal document converter.
Re: Please do not attempt to simplify this code
#77Earlier quoted context omitted.
> do other HNers also feel that a high comment:code ratio probably indicates quality? I consider it a big risk of errors. When some code is changed, will all related comments be rewritten too? I doubt it. And then you end up with a codebase which indicate A but comments which clearly spell out B, and you as a maintainer have no idea what to believe. DRY. Don’t repeat yourself. The comments should not double up for th…
Short functions help here. If every function is just a few lines long, the comments are easier to keep synchronized, and if a function drops out of service, it should eventually be garbage collected with its now-irrelevant comments.
But what if comments pertain to unexpected states the system as a whole can be in?
Kind of the whole problem is when there are weird corner cases going on that straddle function boundaries.
I'm not saying that's a good thing; mind you - but nor is it always trivially avoidable, especially if code needs to be concurrency and/or exception safe -- or in general whenever the statements your function consists of have surprising and opaque behavior based on system state, particularly if said state is hard to grasp due to being implicit or dynamic, or simply large and complex.
Re: Please do not attempt to simplify this code
#78Earlier quoted context omitted.
No, I do not find it indicates quality. To me, comments are noise, and code is signal; the code is what actually executes. It's one thing to have a summary of intent at the start of a listing, that should not count towards the code:comments ratio. Once the code begins however, there should be a minimum of comments necessary - especially in a high-level language not constrained to assembly-level instructions. In assem…
Why do you want to abort when prio is in endidle or busy, and not in other cases?
If you care to understand the code I pasted, here's the full listing:
https://github.com/chrislgarry/Apollo-11/blob/master/Comanch...
Re: Please do not attempt to simplify this code
#79"it became clear that we needed to ensure that every single condition was handled and accounted for in the code" This is a feature of several (mostly functional) programming languages, e.g. Haskell. Fun to see that often people figure out that these types of concepts are a smart way to write your code. Too bad it usually means many people reinvent the wheel instead of learning about computer science history and other…
I know a business coach who regularly asks his audience "Who here makes better burgers than McDonalds?". When half the audience raises their hand, he asks them why they don't outsell this giant company. Functional programming advocats, especially for the "pure" ones like Haskell, always strike me as odd. It seems that all the beauty of those languages make people obsess over that beauty and purity while keeping them…
.. that said, Kafka is written in Scala.
Re: Please do not attempt to simplify this code
#80The comment claim that every branch is accounted for and yet few functions below you can see this is certainly not the case. They should either have fixed it first and then make such comment or shouldn't make such comment at all. Otherwise this looks a bit cringey.
It says "(exception: simple error checks for a client API call)" and that seems accurate to me.
In particular Go (like C) has no built-in exception "throwing" / unwinding support, so for any function call where you want to pass an error onto the caller, you need to do something like
result, err := try_to_get_a_result()
if err != nil {
return nil, err
}
(It would be nice in theory if there were better language support for making this lexically obvious but they're in a language where that's not doable.)