Hacker News Reader

Comment by omarhaneef | Hacker News Reader

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.

View on HN

In 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...

Turns into this documentation (the beginning only): https://godoc.org/net/http

Out of the box.

Nice. I like the way it also shows you the functions inside a file/folder, and that clickable index is nice.

What's the point of all these empty comments throughout the code?

    // ...

It's likely the Go libter requiring every public method / variable to be documented.

Yup. I saw a lot of codebases with things like:

// EnqueueEvent ...

func (q *Queue)EnqueueEvent(event Event)

It's just an ellipsis indicating that there be would more code after.

It 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.

readme 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.

Yep. 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.

Java did this with package-info.java. It is underused, in my experience.

Reply on news.ycombinator.com