Hacker News Reader

Comment by michael_j_ward | Hacker News Reader

When I first started programming, I thought the description next to the folder / file name on github was actually describing the item - as you did above, and not just the message from the last commit that altered the file.

Many years later, I still believe that's how it should be.

View on HN

Agree! I gave that feedback many times, who cares about commit message? I want documentation here!

I think Github should really start taking a stance on convention, and come up with project structure conventions that would help project navigation. For example, youtube does that with chapters in videos, if you write a description with timestamps it will display these chapters in the timeline of the video[1].

IMO Github should do the same if you have a README in your folder, describing the folder with a certain syntax, then it should extract this info and show it next to folders.

If anyone at Github is reading this, pretty please :D?

[1]: https://www.youtube.com/watch?v=XfP862hCrDM

I’ve recommitted a number of times just because the last commit message was dumb or useless or worse - wrong.

This makes me think we should be able to put something like a standard tag for a 1-line summary (maybe embedded in some markdown in a comment) in a fashion the VCS's can detect & extract and then render in their UXs.

e.g. something very simple would probably work like the first line found that matches something like:

   [Ignore_Non_Words]Summary[IgnorePunctuation&Spaces](Capture)

You could probably solve most use cases by just pulling the first line from the readme in that folder.

It would encourage people to write folder-level readmes if nothing else.

I think you could get a lot of mileage from using existing formats in code and comments.

So for instance, if save_parser.py starts with

    """ Parse content loaded from save files

    ...

    """

and math_backend.rs starts with

    //! List of data structures necessary for maths operations
    //!
    //! ...

then your source tree UX should look like:

    src
    ├── save_parser.py      # Parse content loaded from save files
    ├── math_backend.rs     # List of data structures necessary for maths operations

Reply on news.ycombinator.com