doc: Go project structure - Intuitiveness of documentation and lack of examples #21039
Comments
Perhaps. Using the ML to ask a question would've in this case probably served you better. A personal opinion: The documentation used to not have the term workspace at all - in the beginning. I think this issue is an example why it should have stayed like that. No one talks about "executespace" when discussing $PATH neither. It's a source of unnecessary confusion. |
bradfitz
changed the title
|
FWIW, this: and this: describe the same directory tree - we just put "github.com/golang/example" together on one line so the text didn't bleed as far to the right. I'm not sure how you are trying to create directories, but if you are using the command line, you can create the directories like this: Or like this: If you are cloning an existing project, you can run "go get github.com/golang/example" and go get will install the packages for you. |
|
CC @spf13 |
|
'Perhaps. Using the ML to ask a question would've in this case probably served you better.' Eventually I figured that and then some more down the text. I agree it looks better concatenated but for a moment or more it can be confusing. mkdir is fantastic example that shall be in the doc. Unfortunately it works only on unix like systems (AFAIK). But whole writeup is not about this one particular thing, this was just a trigger. It is about assumption that someone else will think in the same way as author of the text, and that answers given there are all answers one may ask, whereby after reading it, this particular text raises more questions than it provides answers. GO is not only one who keeps 'import' mechanism under-documented. Another major tool (Python) has similar issues. Even in your answer assumptions are present. Assumption is that one will ONLY want to use other people libraries. Another one is that we will use github. While this is true as a general case for most programmers, it is not true for all of programmers. Some of us will want to create some libraries of our own (which may not be at all interesting for general public or even unavailable because of other reasons), and wander where to find more resources, what pitfalls they may encounter and (if warned early enough) avoid them. What issues we know from another languages and tools we use (take nodejs as example where (micro)library dependency hierarchy gets rampant and versioning goes nuts). Not to mention advanced topics such as dynamic library import (that changes depending of use and conditions) that are possible in scripting languages and virtually not possible in Go since it is compiler (unless we have some dynamic library loading mechanism - and why we shall have that in Go?). So what is this? It is a cry to have better documentation. It is a cry to have documentation feedback system. It is a cry to make it more understandable for people who may not have experience or even for ones that have experience but they do not find answers or do not find them easily. I have also read several books about go. Lets take example of one freely available (but rather beginners related and rather rudimentary) book - the discussion about exporting of variable or function from a module takes one whole sentence hidden at the end of a paragraph. I believe that one of very basic and important subject such are scope, visibility and export deserve more than just mentioning it in one sentence. Books you pay to get are not much better. Again why? Because i see GO really as replacement to C. I've been waiting for decades that someone dares to challenge C and OO for that matter, and while we are at it, I believe GO deserve to be good (as code) but also well documented (one would expect that knowledge has accumulated over decades, but funny part is that some mistakes are commonly repeated when it comes to software). Luckily GO has some guru protection level, so I am confident we are good on a long run. |
|
I don't think there's much that's actionable here, and I expect this doc to be completely rewritten next cycle. |
Please answer these questions before submitting your issue. Thanks!
Assumption that the issue may not be code issue can become helpful. I have read 'the guidelines for contributing' and find they do not apply to my problem.
What version of Go are you using (
go version)?several, depending on system and history started somewhere around v.0.something way before it got v.1. But, I am not yet using it actively. (Perhaps some of below is why)
What operating system and processor architecture are you using (
go env)?Linux amd64, Windows amd64, OSX (I also tried GO on Android...)
What did you do?
read the documentation (RTFM)
What did you expect to see?
a method how to create folder "github.com/golang/example/" under linux (or windows, or osx, I would not have a problem to do that on MacClassic, I guess)
What did you see instead?
https://golang.org/doc/code.html#Workspaces
I am trying to make a joke here but there are serious problems I encountered when reading this document and this is rare document that talks about stuff not explained elsewhere.
I can however make this...
but that beats the purpose of being presented nicely. 'Nicely' does not do it, real life is more ugly and I am still unsure that I do it right (because it is later import "github.com/golang/example")
But seriously this document is pretty un-intuitive and simplified and looks like done in haste, while it explains some bits and pieces of the structure it does not answer several important questions such are:
How I handle several different projects code with go? (more complex structures)
What I wish to make my organization of code (for other reasons, say, I am writing application code using several different programming languages and systems and wish to get out from the rigid folder structure of go and keep my organization of code per my project not per go project (Go is not only one who is suffering of self-centralism as if there is nothing else existing under the sky. Most programming languages do suffer of same self centralism, some more some less) Yes yes, I know, most of the people cannot handle more than one programming language at a time. And, I can make a mickey mouse .go and compile at the spot so I am not that of a disadvantage (eventually I can hid a go workspace within another project).
I am completely mesmerized by go's "import". It is so poorly described that when experimenting with how to actually successfully compile anything more complex than hello world (eg add local and external libraries that I would write) i run into several hours of frustration to make it right. And I did not find all use cases and/or designer thoughts in one place. I get hints all around web in people blogs. Give more source examples like - if you wish to achieve this - you need to write this. Python3 import is very look-a-like pretty same mesmerizing.
Honestly, can you kindly improve on this document and give it a way more examples how code place and imports look like. I do not see the point of being hit with elaborating as to why error shall be outside of os library when beginner do not know even how to deal with basics structure of a project. (Maybe it is because I use gogland and it got excited on not letting me do things my way, even that this is wrong way but which is intuitive to me. Go(gland) is not only IDE that has frustrated me, at certain point LiteIDE drove me nuts so much that I made it work but in the same time gave in. To be honest if there was not these IDE's to help on structure the project I would possibly never make it right by hand).
Or, maybe, because a small voice cannot beat voices of engineers doing large and important stuff like running Google, Amazon, Cloudflare or academic papers. If you wish to replace C, kindly understand that C success was made because of a lot of 'small' people using it.
Toss in to this document exporting and not exporting names from libraries just to warn beginner as to what is private and what is public when they create structures (since extern is not there AFAIU) it is intuitive that mylib.MyFunction and mylib.myFunction are different but what is not obvious that they are different in some other more subtle ways. Even by reading books this would be hard to spot one paragraph of explanation.
And add why
package mainis different thanpackage whateveris itpackage mylib.whateverorpackage downloadlib/whateverand why it is not either, especially that later it becomes import "mylib/whatever" (where this came from? which part of galactic GOPATH is serving it). (to this note, I am perfectly aware of C's ability to inheritmainfrom an obj/library, which GO elegantly strive to avoid)Finally it is not very clear to me that what the document says 'A workspace contains many version control repositories (managed by Git, for example).' is achieved? What do I do with package version 0.3, 1.0.9, or 5.20.9017? Perhaps I need 2.1 and contemporary idea and latest craze is package 4.5. Shall I import "github.com/ljgww/mylib/0.3" and what if I am ok wih 0.3 thru 0.5 but not OK with 0.9?
Go has tendency to make programmers world a flat list (that's how I feel it). Give us more of hierarchy in our own expressions. I am still mesmerized with the concept of 'workspace' and path scope to it. I did not try it as yet, but I guess I can do serious juggling with GOPATH achieving nice effects.
You may close this ticket it does not propose any bug in code. I hope it was worth spending time to write it. Perhaps it is just in the wrong place. I also accept the fact that I may be stupid, computers have told me that several times, even that people generally would not. I take it, if I am stupid, I hope I deserve the right to be stupid in my way at least.
If I have one reader reading this to this point I will be happy.
The text was updated successfully, but these errors were encountered: