OSDev.org

ehird wrote:Plan9's gui is an artifact of the 90s that nobody's worked on recently.

IMHO it's pretty ugly for 90s as well....

OK then, mid-eighties.

ehird wrote:~: It's hardly simplistic when the linux coding guidelines dictate that a function should generally not exceed 24 lines, and that any more than 3 levels of indentation means you probably are doing something wrong.

I didn't complain about that, but there's certainly much more to code clarity than those guidelines.

I document Purpose, Precondions and Postcondition for most of my functions, this way, if I come back to it a couple months later, I know what each function does and the conditions required before the call , and the state after.

Also I try to keep each function doing only one thing (except in a few performance critical situations). It helps the code become easily maintainable.

@~ With good (remember with documentation quality is better than quanity) documentation and program stucture, here should be not many cases where you need to explain you code.

ehird wrote:- Vim emulates a lot of gui stuff inside a terminal - that's just backwards.

Uh?

I know what you mean, and have seen some memacs-variants doing it, but I haven't seen vim doing that, ever. If your OS' vim does that by default, blame the person who packed the package, as it certainly isn't something vim does out-of-the-box.

Um, yes it is. ncurses. ncurses is fatally incorrect. It gives gui-style control over a "screen" emulated with text and uncooked mode. That belongs in a >real< GUI.

Now it still seems to me that there aren't many more things to do than those already said here. Or in other words, it would be better to make a well structured documentation on the algorithms, the design and the implementation and then let the programmer make as many hacks and unclear code as he likes, and if somebody wants to understand it then just let them look through the fine documentation for even being able to reprogram it completely.

ehird wrote:Um, yes it is. ncurses. ncurses is fatally incorrect. It gives gui-style control over a "screen" emulated with text and uncooked mode. That belongs in a >real< GUI.

Strongly disagree.

You are trying to say that we should always (no exceptions) read the console line-by-line letting the terminal to provide line editing it feels like it, because asking for the raw character-per-character input is "incorrect"?

You are trying to say that we should only use dump terminals, because the escaping features such as those offered by VT100 are "incorrect"?

You are mistaken.

~ wrote:...and then let the programmer make as many hacks and unclear code as he likes, and if somebody wants to understand it then just let them look through the fine documentation for even being able to reprogram it completely.

No need to be so negative. It is just a fact that not everything can, or even should, be documented directly within the code. Too much comment renders the code unreadable. Too little comment does the same.

A real-life example. One of the first code modules I wrote professionally was to determine the volatility of a data series. Just a small wheel in a large machinery of code for a big bank.

First, we wrote a document specifying what "volatility" actually meant, so that both the customer and our little software company were sure that both sides had the same understanding of the subject. Any derivations from that documentation would have to be added to that document anyway, if only to avoid legal consequences should our software belch up the wrong numbers.

The documentation contained references to and quotations of several books on the subject, including the formula for "volatility".

The module I wrote started with a comment header that described how data should be passed to the module, how the result was passed by the module, and where to find the documentation.

The code was sprinkled with comment lines, usually in front of loops or in the first lines of if / else alternatives, to allow quick browsing of the code without actually deciphering the code itself. That means, someone looking for a bug could rapidly get to the piece of code that does the wrong thing.

Simply re-phrasing each code statement in English would not have improved documentation or readability, but would merely add redundant "noise", which could at worst be misleading when it tells the reader the next statement does "X" when it doesn't because it's buggy. As it were, my comments gave a red line of what I was trying to achieve, giving those who came after me an easier time understanding the overall structure and finding those places where I may have glitched.

At one point (directly above the actual calculation), there was a three-line comment block, stating that the code did the actual calculation using the formula from the documentation in transposed form, and the reason (the result would have been lost in the limited precision of floating-point maths otherwise). I didn't add that to the printed documentation, because it was effectively the same formula, and the one in the printed documentation was the one canonically used in the business, whereas the transposed version was a mere technicality. (*)


I think that module was about as readable and well-documented as code could be, and I actually received high praise for it, with a code-statement to comment line ratio of about 5:1 and no "rules" other than common sense and my own pride being applied.

Comments are a good thing, and should be encouraged. But writing good comments is a coder skill, the comment part of the stuff I call "code", and no amount of rules will make a bad coder writing better code. Don't look for larger or stricter rule sets "enforcing" better code, look for better coders, or educate them.


(*): Think of it as "information scope". When you're looking for the reason of a database exception, you aren't interested in that transposition, you want to step through the code to find the database access ASAP, and if you found it, you want some hint as to what was intended (because obviously the code doesn't work as intended and you have to fix it) - and you look for it next to the actual statement.
If you are interested in using the module, you aren't interested in the formula or its transposition, you're interested in the interface - and look at the comment right at the interface definition.
If you are a business person and interested in whether the module already uses that nifty new formula from the new book, you aren't interested in source at all, you look at the module's documentation.
The only person interested in the transposition stuff is a person that suspects the calculation is doing something wrong, and thus is looking at the calculation itself, so that is where the transposition should be documented.

Sure, you could put all the documentation - business, interface, database, calculation - in one place, on paper or in the code. But you would simply drown the useful info in lots of uninteresting stuff, for anyone looking for information.

mystran wrote:

ehird wrote:Um, yes it is. ncurses. ncurses is fatally incorrect. It gives gui-style control over a "screen" emulated with text and uncooked mode. That belongs in a >real< GUI.

Strongly disagree.

You are trying to say that we should always (no exceptions) read the console line-by-line letting the terminal to provide line editing it feels like it, because asking for the raw character-per-character input is "incorrect"?

You are trying to say that we should only use dump terminals, because the escaping features such as those offered by VT100 are "incorrect"?

You are mistaken.

Yep, this is my opinion. Completion and line-editing is terminal-level, not hacked-on-lib level. I also believe that if you want an interface like vims you should stop forcing the terminal to it, and use a proper gui library instead.

Uh-huh... you mean, everytime I want to edit a remote file with some convenience, I have to have an X Server running?

I don't think so.

SSH, X forwarding. No X server needed on the server.

..but rather, needed on the client as Solar said.

Not nice on windows users, you are

Hey, we're talking about minimalist UNIX-extremes design here. Windows doesn't really come into the equation

Weren't we talking about code delimitation at the beginning?

This hardly helps complete points of view about that very topic, , but anyway, let's keep going... to... an useful talk...