Practical Go: Real-world advice for writing maintainable Go programs • Hacker News Board

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

#81

Post by bennofs » Thu, Feb 21, 2019, 8:43 PM UTC

jerf wrote: post #76

diegs wrote: post #71

About half-way through and I think this is a great article, in particular the quotes and I also agree that the first 4 sections are generally applicable. One thing I disagree with is the remark about having fewer, big packages. Though conceptually I agree that avoiding having too many public APIs that aren't widely used makes sense, in practice --at least on the types of projects I tend to work on--I find that direct…

I agree with you. I like the way packages are isolated from each other, meaning that to understand a package it is usually by definition a good start to simply read what is there. Smaller packages mean more bite-sized chunks of the program. And I think the discipline of slicing up your program this way is very, very good for the design, and often makes the tests easier to write to by significantly shrinking the surfa…

If packages are too small it can get hard to understand the code if your not familiar with the structure yet. Working from bottom to top level can work but might also be different because you are missing context for the low level packages to make sense.

In general I found larger packages tend to produce more direct / pragmatic code with less indirection which is usually easier to understand, even though it also feels wrong to me from a theoretical standpoint.

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

#82

Post by weberc2 » Thu, Feb 21, 2019, 8:58 PM UTC

jstewartmobile wrote: post #32

weberc2 wrote: post #29

Earlier quoted context omitted.

Disagree hard on Go vs Python. Python is my day job, but documentation is rough . You're likely not going to get documentation for all the types, and if you do it's usually in one giant page and you can't tell which class's `__str__()` docstring you're looking at. Often you'll have a method with some terse description for parameters that don't completely describe the types accepted for a parameter. Most of this stuff…

I'm mostly comparing this: http://flask.pocoo.org/docs/1.0/api/#api to this: https://golang.org/pkg/net/http/ If the source weren't hyperlinked, I'd be lost on the latter. edit: I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code.

First of all, https://godoc.org/net/http is the page to visit; it serves documentation for all public packages, not just the standard library, and it's generally a little nicer. That everything is on the same site is a big deal because maintainers don't have to link to their dependencies and readers don't have to deal with the inconsistent presentation of documentation across the ecosystem.

The distinction I see is that someone put a lot more care into Flask's documentation (including the theme, which is actually a little hard to read since it renders certain things in small italic font), which is great but not indicative of the broader ecosystem. The most significant distinction wrt readability is that the Go page has types for _every_ parameter with links to the type definition. For all of the care put into the Flask doc, you still see things like this all over:

> view_func – the function to call when serving a request to the provided endpoint

I have no idea what the signature of that callback is. Meanwhile Go has https://godoc.org/net/http#HandleFunc which clearly shows the type for the handler callback (with links to types):

    func HandleFunc(pattern string, handler func(ResponseWriter, *Request))

> I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code.

I tried to use Racket (it looks really neat), but I just spent so much time trying to figure out what to pass into each function. It was nearly impossible since types are often absent. That's just not how I want to spend my free time. :(

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

#83

Post by krat0sprakhar » Thu, Feb 21, 2019, 8:58 PM UTC

Slightly offtopic: Does anyone know which template was used to generate this document? I'm assuming the source in markdown and I really like that the generated html has table of contents, support for footnotes and is responsive!

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

#84

Post by jstewartmobile » Thu, Feb 21, 2019, 9:04 PM UTC

AnimalMuppet wrote: post #72

jstewartmobile wrote: post #18

Love Mr. Cheney, hate stuff like this. Someone who has put the hours in will probably stray from all of this advice, and still end up with something beautiful. Meanwhile, for all of the other schmoes who haven't put the hours in, this is just more fuel for screeching about how this name isn't right or that comment is too long. Dijkstra said GOTO was bad, and now we have callback hell and 10-layer inheritance hierarch…

If you're writing the kind of thing where you need callbacks, GOTO isn't going to make it more clear what's going on...

Never said it would. I did imply that things haven't significantly improved.

Throw away goto and globals, replace them with anonymous functions and closures, and the new thing looks an awful damn lot like the old thing.

All I know is that we used to have retrained housewives writing physics programs. Now we expect 10,000 hours to write a halfway decent web form, and halfway decent doesn't happen nearly as often as it should.

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

#85

Post by akerl_ » Thu, Feb 21, 2019, 9:05 PM UTC

pcwalton wrote: post #44

akerl_ wrote: post #36

Earlier quoted context omitted.

The issue w/ calling it "config" is that you end up with the confusing scenario where "config" is the object and "Config" is the type, differing only in casing.

Why is that confusing? Local variables are, idiomatically, never capitalized in Go, so the distinction is obvious at a glance.

Sorry. To clarify: it's not that I'm confused by the distinction between capitalized vs uncapitalized, it's that visually, "config" and "Config" look quite similar at a glance, whereas "c" and "Config" are clearly visually distinct.

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

#86

Post by jstewartmobile » Thu, Feb 21, 2019, 9:08 PM UTC

weberc2 wrote: post #82

jstewartmobile wrote: post #32

Earlier quoted context omitted.

I'm mostly comparing this: http://flask.pocoo.org/docs/1.0/api/#api to this: https://golang.org/pkg/net/http/ If the source weren't hyperlinked, I'd be lost on the latter. edit: I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code.

First of all, https://godoc.org/net/http is the page to visit; it serves documentation for all public packages, not just the standard library, and it's generally a little nicer. That everything is on the same site is a big deal because maintainers don't have to link to their dependencies and readers don't have to deal with the inconsistent presentation of documentation across the ecosystem. The distinction I see is t…

That sounds like a stronger defense of types than Go's documentation.

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

#87

Post by ra7 » Thu, Feb 21, 2019, 9:21 PM UTC

xtian wrote: post #74

ragona wrote: post #42

Earlier quoted context omitted.

> 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…

See: http://number-none.com/blow/john_carmack_on_inlined_code.htm...

The summary is great:

> If a function is only called from a single place, consider inlining it.

> If a function is called from multiple places, see if it is possible to arrange for the work to be done in a single place, perhaps with flags, and inline that.

> If there are multiple versions of a function, consider making a single function with more, possibly defaulted, parameters.

> If the work is close to purely functional, with few references to global state, try to make it completely functional.

> Try to use const on both parameters and functions when the function really must be used in multiple places.

> Minimize control flow complexity and "area under ifs", favoring consistent execution paths and times over "optimally" avoiding unnecessary work.

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

#88

Post by apoorvgarg » Thu, Feb 21, 2019, 9:23 PM UTC

pcwalton wrote: post #48

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?

Yeah, I used to go by this advice, and I found the maintainability of my code dramatically increased when I typed out full names. I don't even use "i" for loop variables anymore. If the length is a problem, invest in an editor with autocomplete. Well-known abbreviations are fine, like "iter" and "prev", but single-letter variable names notoriously impede readability for me.

Regarding single-letter variables, mathematical functions might be an exception. I think writing func gcd(a, b int) int {...} is better than other alternatives. There is simply no need to assign any more meaning to the arguments other than their type.

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

#89

Post by andriosr » Thu, Feb 21, 2019, 9:27 PM UTC

OutsmartDan wrote: post #4

Would love to see better separation on the page between "Bad" and "Good" examples. While a good read, it's difficult to quickly distinguish between the two. For example: https://github.com/airbnb/javascript

true. Google will index it and I can see many people copy and paste bad code considering the best practice for doing something

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

#90

Post by [deleted] » Thu, Feb 21, 2019, 9:33 PM UTC

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?

[deleted]