Practical Go: Real-world advice for writing maintainable Go programs

Post by q3k » Thu, Feb 21, 2019, 7:37 PM UTC

michaelcampbell wrote: post #27

TheJazi13 wrote: post #7

Earlier quoted context omitted.

I’d argue there’s a failure of the code to some extent to need such extsenibility with documentation. I’ve often found when I need more info outside of Godocs that simply clicking through and diving into the source provided me with all the answers I needed to know.

Yeah, every time I need to know why my car isn't working correctly, I take it apart. All the answers I could possibly want.

Post by bch » Thu, Feb 21, 2019, 7:42 PM UTC

networkimprov wrote: post #38

briatx wrote: post #35

> Naming the Config parameter config is redundant. We know its a Config, it says so right there. > In this case consider conf or maybe c will do if the lifetime of the variable is short enough. This seems petty. Is it really that problematic to type out a few extra characters?

And this is worse advice: > Functions should do one thing only. ... In addition to be easier to comprehend, smaller functions are easier to test in isolation, and now you’ve isolated the orthogonal code into its own function, its name may be all the documentation required. Using single-caller functions as a substitute for comments makes the workings of a specific operation much harder to follow, as you have to jump a…

Post by entity345 » Thu, Feb 21, 2019, 7:48 PM UTC

networkimprov wrote: post #38

briatx wrote: post #35

> Naming the Config parameter config is redundant. We know its a Config, it says so right there. > In this case consider conf or maybe c will do if the lifetime of the variable is short enough. This seems petty. Is it really that problematic to type out a few extra characters?

And this is worse advice: > Functions should do one thing only. ... In addition to be easier to comprehend, smaller functions are easier to test in isolation, and now you’ve isolated the orthogonal code into its own function, its name may be all the documentation required. Using single-caller functions as a substitute for comments makes the workings of a specific operation much harder to follow, as you have to jump a…

Post by networkimprov » Thu, Feb 21, 2019, 7:49 PM UTC

ragona wrote: post #42

networkimprov wrote: post #38

Earlier quoted context omitted.

And this is worse advice: > Functions should do one thing only. ... In addition to be easier to comprehend, smaller functions are easier to test in isolation, and now you’ve isolated the orthogonal code into its own function, its name may be all the documentation required. Using single-caller functions as a substitute for comments makes the workings of a specific operation much harder to follow, as you have to jump a…

> A long function is easier to understand than an exploded one. This is a pretty controversial position, and quite situational in my opinion. I absolutely agree that having to hop all over the source to understand something is frustrating, but that doesn't mean that very long functions are the right solution. Some combination of reasonably named helper methods and a function flow that makes the logic easy to parse sh…

Post by entity345 » Thu, Feb 21, 2019, 7:50 PM UTC

arendtio wrote: post #16

> A good Go package should strive to have a low degree of source level coupling such that, as the project grows, changes to one package do not cascade across the code-base. I wonder though why there is so little emphasis on how important interfaces are in Go. I mean, section 4.5 talks about it a bit, but in my experience, this mistake is made far too often.