Hacker News Reader

Comment by kpozin | Hacker News Reader

I've been looking through some of the kernel code [1] out of curiosity, and I'm very surprised to see that most components have almost no internal documentation — minimal file and class comments, and even fewer inline comments. Is this typical of code for something as complex and central as an OS kernel? Are the developers planning to go back later and add documentation, or is the expectation that anyone who might need to work with this code will find its structure and details intuitive?

[1] https://github.com/redox-os/redox/tree/master/kernel/

View on HN

Yes, I like to read sources of big projects as a relaxing activity and almost never is documentation written in a way that a newbie can immediately catch up. The best projects will have a README.md in every directory that explains what a component or namespace is about, or nice big documentation headers. In my experience though if you really want to contribute the lack of documentation is only a small hurdle. If the code is well written then just following the code from the entrypoint on will give you a very good idea about what's going on. All the files and their names should make sense in under an hour or two.

In my opinion documentation is most important for external consumers of APIs who don't want to spend time grokking the code, and for explaining design decisions. For contributors it would be code quality.

There is this comment :) ..

    /// Into a cow
    pub fn into_cow<'a>(self) -> CowUrl<'a> {
        /*
             ______________
            < Mooooooooooo >
             --------------
                    \   ^__^
                     \  (oo)\_______
                        (__)\       )\/\
                            ||----w |
                            ||     ||
         */
        CowUrl::Owned(self)
    }

I only took a brief look over the code to try to find what documentation is actually there, but I managed to find this

https://github.com/redox-os/redox/blob/master/kernel/fs/url....

On your question of how typical a lack of system-internal documentation is in systems projects, the answer from my experience is unfortunately more common than it should be. There are a bunch of usage and design patterns that cannot be expressed regardless of the language you are using. I know very little about Rust, but I work mostly in Java, which is safer than many other languages (less flexible than interpreted or dynamic languages, less dangerous than C/C++). Even java, which has interfaces and strict typing can save you some of the more mundane unit tests and input validation code, has a bunch of design patterns on top of the core language. Projects could serve themselves well to document their code well to allow new contributors to look at any of the code and reasonably modify it to fix a bug or add a feature.

In java, the jvm is the OS. Every object in Java is allocated in the heap, and doesn't provide developers direct control of a more optimized way of allocating objects. In rust, you can specify an object to be on the stack or on the heap, rust compiler is very smart and it knows where an object goes out of scope, thus not needed anymore and insert a code on that location to drop that object and free memory. Unlike in Java, which waits for the garbage collector to drop objects.

In a nutshell, java engineering effort is directed into the jvm(jit) to provide high performance when the applications are run. Rust engineering, on the other hand is directed on the compiler figuring out where and when an object is out of scope, no matter how complex it was attached to other objects, passed around multiple functions. It will figure it out.

That's not really how it works. Rust's rules for when an object is freed are very simple, basically the same as C++- they don't depend on references or anything. The complicated part is that the compiler makes sure no references to an object exist after this predetermined point in the program.

There appears to be a book that serves as documentation, though I don't know how complete it is: http://www.redox-os.org/book/book/

Reply on news.ycombinator.com