News for hackers. Stuff that matters.
Re:Ask HN: What are the “best” codebases that you've encount... by omarhaneef on Monday July 29, 2019 @02:02PM (#20557440)
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.

Re:Ask HN: What are the “best” codebases that you've encount... by PhilippGille on Monday July 29, 2019 @02:51PM (#20557990)
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.

Re:Ask HN: What are the “best” codebases that you've encount... by omarhaneef on Monday July 29, 2019 @03:04PM (#20558145)
Nice. I like the way it also shows you the functions inside a file/folder, and that clickable index is nice.
Re:Ask HN: What are the “best” codebases that you've encount... by heyoni on Monday July 29, 2019 @05:37PM (#20559717)
What's the point of all these empty comments throughout the code?

    // ...
Re:Ask HN: What are the “best” codebases that you've encount... by patrickmcnamara on Monday July 29, 2019 @08:29PM (#20560976)
It's just an ellipsis indicating that there be would more code after.
Re:Ask HN: What are the “best” codebases that you've encount... by hazz99 on Monday July 29, 2019 @08:12PM (#20560873)
It's likely the Go libter requiring every public method / variable to be documented.
Re:Ask HN: What are the “best” codebases that you've encount... by inlined on Tuesday July 30, 2019 @04:00AM (#20562919)
Yup. I saw a lot of codebases with things like:

// EnqueueEvent ...

func (q *Queue)EnqueueEvent(event Event)

Re:Ask HN: What are the “best” codebases that you've encount... by aerlinger on Monday July 29, 2019 @02:57PM (#20558062)
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.
Re:Ask HN: What are the “best” codebases that you've encount... by dguo on Monday July 29, 2019 @03:06PM (#20558185)
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.

Re:Ask HN: What are the “best” codebases that you've encount... by omarhaneef on Monday July 29, 2019 @03:05PM (#20558163)
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.

Re:Ask HN: What are the “best” codebases that you've encount... by mcculley on Monday July 29, 2019 @02:35PM (#20557810)
Java did this with package-info.java. It is underused, in my experience.