3 ms·

Because sometimes, there's "No Other Way(TM)". Arbitrary line limits tend to unnecessary fragmentation. Add includes, licenses, glue code and comment; and you

Because sometimes, there's "No Other Way(TM)". Arbitrary line limits tend to unnecessary fragmentation. Add includes, licenses, glue code and comment; and you have an unapproachable spaghetti. Try to keep methods to 200 lines in high performance code, and see your performance crash and burn like Icarus' flight. When you read the comments in the code, you can see that they simplified the code to a single module, and embedded enormous amount of know-how to keep the code approachable and more importantly, sustainable. For someone who doesn't know the language or the logic in a piece of code, the set of comments which outline what the code does is very helpful. In six months, your code will be foreign to you, so it's useful for you, too. Comments are part of the code and the codebase. If you're not updating them as you update the code around them, you're introducing documentation bugs into your code. Just because the compiler doesn't act on them doesn't mean they are not functional parts of your code. In essence they're your knowledge, and lab notebook embedded in your code, and it's way more valuable in maintaining the code you wrote. They are more valuable than the code which is executed by the computer. Best practices are guidelines, not laws or strict rules. You apply them as they fit to your codebase. Do not obey them blindly and create problematic codebases. Sometimes you have to bend the rules and make your own, and it's totally acceptable when you know what you're doing.

johnnyanmac 2y ago
> Try to keep methods to 200 lines in high performance code, and see your performance crash and burn like Icarus' flight. Are these loops in Kubernetes so hot that extra microseconds for some program stack manipulation will affect performance? I never took Kubernetes as a hyper-real time application. >Do not obey them blindly and create problematic code bases. I don't know the code so won't question it specifically, but wouldn't this also apply to "space shuttle programming"? I feel Space shuttle programming's job in many ways is in fact to try and remove ambiguity from code. But not by explaining the language, but the variables and their units. I sure wouldn't mind spamming "units in cm" everywhere or explaining every branch logic if it's mission critical. Not so much this inconsistent doxygen/javadoc style documentation on every variable/class. If you're going to go full entrprise programming, commit to it. Above everything else, the big thing going through my mind reading these are "a proper linter configuraion would have really helped enforce these rules".
- bayindirh 2y ago
  > Are these loops in Kubernetes so hot that extra microseconds for some program stack manipulation will affect performance? Actually, looking at the code itself, pv_controller doesn't look overly hot, but extremely high value. In this case the long methods are intended to keep the logic confined, so one can read end to end and understand what is going on. The code even doesn't use automatic type inference in Go (the := syntax), in some cases to make code more readable. From what I understand, this code needs to be "kernel level robust", so they kept the overly verbose formatting and collected all three files to a single, overly verbose file. I don't think this is a bad thing. This is an important piece of a scale-out system which needs to work without fault (debate of this is another comment's subject), and more importantly it's developed by a horde of people. So this style makes sense to put every person touching the code on the same page quick. > I feel Space shuttle programming's job in many ways is in fact to try and remove ambiguity from code. But not by explaining the language, but the variables and their units. I sure wouldn't mind spamming "units in cm" everywhere or explaining every branch logic if it's mission critical. A code comment needs to explain both the logic, and how the programming language implement this logic the best way possible. In some cases, an optimized statement doesn't look like what it's doing in the comment above it (e.g. the infamous WTF? comment from id Games which does fast_sqrt with a magic number). In these cases I open a "Magic Alert" comment block to explain what I'm doing and how it translates to the code. This becomes more evident in hardware programming and while working around quirks of the hardware you interface with ("why this weird wait?", or "why are you pushing these bytes which has no meaning?"), but it also happens with scientific software which you do some calculation which looks like something else (e.g.: Numerical integration, esp. in near-singular cases). > Not so much this inconsistent doxygen/javadoc style documentation on every variable/class. If you're going to go full entrprise programming, commit to it. This is not inconsistent. It's just stream-of-consciousness commenting. If you read the code from top to bottom, you can say that "aha, they thought this first, then remembered that they have to check this too, etc." which is also I do on my codebases [0]. Plus inline comments are shown as help blobs by gopls, so it's a win-win. I personally prefer to do "full on compileable documentation" on bigger codebases because the entry point is not so visible in these. > "a proper linter configuraion would have really helped enforce these rules". gopls and gofmt do great job of formatting the codebase and enforcing good practices, but they don't touch documentation unfortunately. [0]: https://git.sr.ht/~bayindirh/nudge/tree/master/item/nudge.go https://git.sr.ht/~bayindirh/nudge/tree/master/item/nudge.go

johnnyanmac 2y ago

> Try to keep methods to 200 lines in high performance code, and see your performance crash and burn like Icarus' flight. Are these loops in Kubernetes so hot that extra microseconds for some program stack manipulation will affect performance? I never took Kubernetes as a hyper-real time application. >Do not obey them blindly and create problematic code bases. I don't know the code so won't question it specifically, but wouldn't this also apply to "space shuttle programming"? I feel Space shuttle programming's job in many ways is in fact to try and remove ambiguity from code. But not by explaining the language, but the variables and their units. I sure wouldn't mind spamming "units in cm" everywhere or explaining every branch logic if it's mission critical. Not so much this inconsistent doxygen/javadoc style documentation on every variable/class. If you're going to go full entrprise programming, commit to it. Above everything else, the big thing going through my mind reading these are "a proper linter configuraion would have really helped enforce these rules".

bayindirh 2y ago
> Are these loops in Kubernetes so hot that extra microseconds for some program stack manipulation will affect performance? Actually, looking at the code itself, pv_controller doesn't look overly hot, but extremely high value. In this case the long methods are intended to keep the logic confined, so one can read end to end and understand what is going on. The code even doesn't use automatic type inference in Go (the := syntax), in some cases to make code more readable. From what I understand, this code needs to be "kernel level robust", so they kept the overly verbose formatting and collected all three files to a single, overly verbose file. I don't think this is a bad thing. This is an important piece of a scale-out system which needs to work without fault (debate of this is another comment's subject), and more importantly it's developed by a horde of people. So this style makes sense to put every person touching the code on the same page quick. > I feel Space shuttle programming's job in many ways is in fact to try and remove ambiguity from code. But not by explaining the language, but the variables and their units. I sure wouldn't mind spamming "units in cm" everywhere or explaining every branch logic if it's mission critical. A code comment needs to explain both the logic, and how the programming language implement this logic the best way possible. In some cases, an optimized statement doesn't look like what it's doing in the comment above it (e.g. the infamous WTF? comment from id Games which does fast_sqrt with a magic number). In these cases I open a "Magic Alert" comment block to explain what I'm doing and how it translates to the code. This becomes more evident in hardware programming and while working around quirks of the hardware you interface with ("why this weird wait?", or "why are you pushing these bytes which has no meaning?"), but it also happens with scientific software which you do some calculation which looks like something else (e.g.: Numerical integration, esp. in near-singular cases). > Not so much this inconsistent doxygen/javadoc style documentation on every variable/class. If you're going to go full entrprise programming, commit to it. This is not inconsistent. It's just stream-of-consciousness commenting. If you read the code from top to bottom, you can say that "aha, they thought this first, then remembered that they have to check this too, etc." which is also I do on my codebases [0]. Plus inline comments are shown as help blobs by gopls, so it's a win-win. I personally prefer to do "full on compileable documentation" on bigger codebases because the entry point is not so visible in these. > "a proper linter configuraion would have really helped enforce these rules". gopls and gofmt do great job of formatting the codebase and enforcing good practices, but they don't touch documentation unfortunately. [0]: https://git.sr.ht/~bayindirh/nudge/tree/master/item/nudge.go https://git.sr.ht/~bayindirh/nudge/tree/master/item/nudge.go