Hacker News Reader

Comment by igl | Hacker News Reader

No one ever mentions formatting.

I really like aligning multiline blocks, adding whitespace and useless braces here an there. e.g: Having just a single space between function name and arguments makes it look less like a call. Yet almost all lint presets/defaults forbid this. Typography is all about the whitespace between letters forming easily recognizable shapes.

View on HN

I like to break lines and use indentation to line up repeated text, so you can see there is repetition, and so the parts that are different are obvious. A simple example:

    if ((mouse.x == 0) &&
        (mouse.y == 0)) {

scores more points than:

    if ((mouse.x == 0) && (mouse.y == 0)) {

maybe if(mouseIsAtOrigin()){

The point wasn't to come up with the best api, but to illustrate how to format code that has repetitions and regular variations in it, to make it easy to visually identify which parts repeat and which parts vary. That makes it easier to read the code and spot errors.

For example:

    sqrt((x * x) +
         (y * y) +
         (z * z));

You can run your eyes up and down each column to verify it's squaring x, y and z.

That reflects the structure and symmetry of the expression better than:

    sqrt((x * x) + (y * y) + (y * z));

Did you spot the error?

    sqrt((x * x) +
         (y * y) +
         (y * z));

How about now?

Here's some code that has a lot of examples of that style, a JavaScript implementation of a weird hybrid Margolis cellular automata neighborhood, which has a lot of two-dimensional patterns:

https://github.com/SimHacker/CAM6/blob/master/javascript/CAM...

That really only makes sense if you've got a 40 year old code base that supports every platform conceived, some of which have mouse origins that are -42.333f or can only be determined at run time.

Take a look at the source for tcsh, this is exactly how it is done there. Unless you're interested in supporting a long dead platform - it makes things unnecessarily complex. I love tcsh, but so many ifdefs in so many static functions...

All this is solved by a linter though, there's no point even trying to remember this, just define your linter rules and let it deal with it.

It might not be the default linter styles, but set up your linter for your project and give your mind more important things to focus on.

A linter is also a great way to jump start learning a new language. If you encounter a warning that doesn't make sense to you, look it up. You'll start to get familiar with common language pitfalls without actually getting burned by any of them.

I didn't know linters had become so advanced. Can you recommend any which work on DSLs (including custom ones), and warn about 2D alignment issues? For example, here's some Nix code I have open right now:

     annotateAsts    = import ./annotateAsts.nix    { inherit stdenv annotatedb;    };
     runTypes        = import ./runTypes.nix        { inherit stdenv annotatedb jq; };
     dumpAndAnnotate = import ./dumpAndAnnotate.nix { inherit downloadAndDump;      };

It would be nice to have a tool rate various equivalent arrangements and warn if it finds one with a significantly better score, e.g. showing me the above if I'd given it something more confusing like:

     annotateAsts = import ./annotateAsts.nix { inherit stdenv annotatedb; };
     runTypes = import ./runTypes.nix { inherit stdenv annotatedb jq; };
     dumpAndAnnotate = import ./dumpAndAnnotate.nix { inherit downloadAndDump; };

Of course, as well as formatting it would be nice for equivalent representations of the same expression to be compared, e.g. using an SMT solver or genetic programming. For example, in Nix the variable names after "inherit" can be in any order, so it's easy to find permutations which highlight common elements (like "stdenv" and "annotatedb" above); if I'd written these in a different order (e.g. "inherit jq annotatedb stdenv;" on line two), it would be nice to be shown rearrangements which score more highly.

It's not just linters either. I can't even find an indenter which handles 2D alignment. For example, indenting something like (random bash code I have open at the moment):

    jq -n --argfile asts        <(echo "$ASTS")                       \
          --argfile cmd         <(echo "$CMD"         | jq -s -R '.') \
          --argfile result      <(echo "$RESULT"      | jq -s -R '.') \
          --argfile scopecmd    <(echo "$SCOPECMD"    | jq -s -R '.') \
          --argfile scoperesult <(echo "$SCOPERESULT" | jq -s -R '.') \
          '{asts: $asts, cmd: $cmd, result: $result, scopecmd: $scopecmd, scoperesult: $scoperesult}'

Emacs wants to put the second '--argfile' directly beneath '-n', which is clearly confusing compared to the above. If linters solve all typography issues, are there any which can be queried for the local-optimal indentation on a line-by-line basis?

Typography is much more than that, of course, but with fixed width plain text, you don't have many options...so ascii art it is. I'm pondering a language that includes formatting abstractions so that you can prepare code for reading along with its functionality (sort of like literate programming, but still starting from code). I would love to see comments in a side bar, long monotonous calls organized into tables, proper spacing and even lines to delimit sections, and so on...

But our current programming systems, we are still very much in the dark ages of code typography.

> I would love to see comments in a side bar

This is brilliant. A neat way to bootstrap getting this sort of thing implemented in most code editors would be to write a plugin that can do this for existing code and make it good enough to turn heads. It would extract documentation blocks to be presented as prose in a vertically split pane to the right and present the file itself with those blocks hidden—as if automatic folding were turned on. It could even apply some fairly simple heuristics to automatically link to other relevant comments. The goal should be an experience indistinguishable from an embedded iframe showing human-generated API docs from the Web.

Another thing I'd like to kill is the file tree that you see in most VCS Web frontends that tell you the last commit message that touched the file/directory, rather than about the structure of the code.

Netscape's old Bonsai tool tried to do something like this. (When Netscape open sourced Mozilla, they also opened up a lot of their internal tools. This is where Bugzilla came from, but there were others, too.) When you were looking at a directory listing, if the file contained what looked like a short description of its purpose in the comments near the top of the file, Bonsai would grab description and present alongside the file name.

In my own projects today, I try to always include a file overview containing a short, single line description and then write a paragraph or two going into further detail, documenting the whys of the code, and generally explaining its overall role in the project/justifying its existence. I'm basically writing for a tool that doesn't exist but that I'd like to see get created and gain widespread acceptance.

There is a tool for literate coffeescript that formats the output in a similar way - you have the english text in a pane on the left and the code in a pane on the right. I quite like the effect -- especially since there are potentially no comments in the code at all, which I often want if I'm just trying to read it quickly.

Unfortunately, literate coffeescript is not really mature enough to be used in a large project, IMHO. However, I hope that more people think about separating human language commentary from computer code. I think the idea behind literate programming is a good one and I hope that it gains some traction some day.

It doesn't really sound like the same thing I'm talking about, to be honest.

And I find the idea of a tool that automatically rewrites machine readable code into a natural language to be of dubious value beyond use cases where someone is first picking up the language. Similar to those tools that exist to generate comments in the form "Set global position" based on a method named setGlobalPosition. It just creates redundancy, and if you're committing the output to your source tree, then it's redundancy in the form of clutter, too.

What I'm thinking of, as I said, should shoot for parity with having a half-screen browser window open to the right containing the relevant docs. Only in this instance the docs are "live", and the lookup process is context-sensitive, requiring very little manual effort to perform it. I know that a basic attempt at something bearing minimal similarity is available in most editors that try to implement Intellisense, but generally I find the helpfulness of the small popup in most implementations to be limited to helping you get the method signature right, and not much else.

One of the nice side effect of the design I'm talking about would be a system that encourages keeping the docs up-to-date and useful as much as it encourage their consumption.

I think you might be misunderstanding what "literate programming" is. It's a method of programming where you embed code inside English language documentation. The idea is to be able to present the documentation in a way that is useful to a human, but have the compiler extract the computer code and reassemble it in the way that the computer would like to see it.

Literate coffeescript does not have the tools for extracting and rearranging text, so it's really just a way of embedding markdown text into your coffeescript code. However, it's useful because you can embed html hyperlinks which can do things like enable you to click to get to the tests, etc.

Here is a small example of something I wrote in literate coffeescript: https://github.com/ygt-mikekchar/react-maybe-matchers/blob/m...

Now imagine that you have the English text on the left hand side and the source code on the right hand side. Ideally you would have tools that would allow you to make the hyperlinks (possibly automatically) and keep the documentation in sync. Such tools do not yet exist at the moment, unfortunately.

Edit: I should admit to being embarrassed about my fluent interface abuse in this code ;-)

Sorry. I'm familiar with literate programming, but I mistook one of your statements:

> formats the output in a similar way - you have the english text in a pane on the left and the code in a pane on the right

... to be a description of a system that didn't really sound like what I had in mind, and didn't really sound like literate programming, either. After reading this comment and a reread of your original one, I understand I was wrong in my interpretation of what you meant. Sorry about that.

This is one thing I do too, and what really bugged me when I first tried Go. As an example I will align equals signs like this:

    loggedIn = foo
    isAdmin  = bar

It doesn't look like much, but when you are glancing over code it really helps to quickly read it.

And then you add `isCurrentlyAllowedToReadPosts = baz` and all your nifty formatting breaks.

This. I can't stand formatting conventions that cause a change to needlessly spill over into the neighbouring lines of a git-blame or diff. It might look good in the 2 dimensions here and now but history is important, and extra lines touched make it harder to follow.

Yes, very important. I love editors that does most of this from a button press. Makes others code easier to understand. Netbeans have lots of settings so you get the braces and spaces where you want them.

Reply on news.ycombinator.com