6 ms·
I wish there was a way to read the codebase where there is a tag that tells you what the folder does. In github, rather than see what has changed, it would be
by omarhaneef 7y ago
I wish there was a way to read the codebase where there is a tag that tells you what the folder does.
In github, rather than see what has changed, it would be interesting if there was a comment that told you what the folder contained.
edit: Relevant here because the best codebase for me is one where I can understand the folder structure, but that is a sort of 0th order effect that should be equalized with some tool.
- mcculley 7y agoJava did this with package-info.java. It is underused, in my experience.
- PhilippGille 7y agoIn Go, a folder is a package and as soon as you write a comment before the `package foo` declaration, it's package documentation. And thus GoDoc automatically generates a nice webpage out of it. See for example this package comment: https://github.com/golang/go/blob/master/src/net/http/doc.go#L6-L104 https://github.com/golang/go/blob/master/src/net/http/doc.go... Turns into this documentation (the beginning only): https://godoc.org/net/http https://godoc.org/net/http Out of the box.
- omarhaneef 7y agoNice. I like the way it also shows you the functions inside a file/folder, and that clickable index is nice.
- heyoni 7y agoWhat's the point of all these empty comments throughout the code? // ...
- hazz99 7y agoIt's likely the Go libter requiring every public method / variable to be documented.
- inlined 7y agoYup. I saw a lot of codebases with things like: // EnqueueEvent ... func (q *Queue)EnqueueEvent(event Event)
- patrickmcnamara 7y agoIt's just an ellipsis indicating that there be would more code after.
- aerlinger 7y agoIt sounds like you're describing a Readme file -- which by convention can exist as documentation for any folder and not just the project root. It's not adopted by all codebases but is becoming more common as source browsers like Github will render the readme as rich text when navigating to the folder.
- omarhaneef 7y agoreadme files might be the natural place for them but in practice readme files sort of tell you about the project, the author, the purpose, examples of what it can do and maybe how to install it. It rarely gives you what is in each folder, and what part of the functionality each folder handles, although perhaps we should try to change the conventions of readme files to include file structure. edit: I mean the root readme might contain what is in each folder so you don't have to click on each one to see which one you want to start with.
- dguo 7y agoYep. For some of the larger projects that I've worked on, I've gotten into the habit of adding folder level READMEs. I don't know if anyone else has benefited from them, but I certainly have myself when I need to remind myself of some context or pitfalls. Having a sensible folder structure and good folder names is nice, but taking a few minutes to write individual READMEs can make a repo even easier to understand.