[thangalin]

Why do we still embed natural language descriptions of source code (i.e., the reason why a line of code was written) within the source code to the exclusion of intrinsically linked separate documents?

http://i.stack.imgur.com/JlUiE.png

The potential advantages include:

- More source code and more documentation on the screen(s) at once

- Ability to edit documentation independently of source code (regardless of language?)

- Write documentation and source code in parallel without merge conflicts

- Real-time hyperlinked documentation with superior text formatting

- Quasi-real-time machine translation into different natural languages

- Every line of code can be clearly linked to a task, business requirement, etc.

- Documentation could automatically timestamp when each line of code was written (metrics)

- Dynamic inclusion of architecture diagrams, images to explain relations, call-graph hierarchies, etc.

- Single-source documentation (e.g., tag code snippets for user inclusion in manual[s]).

[shalmanese]

Because we're stuck in a tyranny of flat text files as a representation of code.

There have been countless proposals over the years for some kind of richer file format for representing code and they have all been busts because so much of our tooling, assumptions, interoperability and culture is centered on flat text code that it's proven impossible thus far to switch.

[krapp]

But text files are easy to generate, easy to edit, and simple to read. What alternatives are there which remain language and tool agnostic?

[sp332]

I can make a file format as tool-agnostic as you like, if it doesn't actually have to have any features.

[Crito]

Being tool-agnostic is a feature. The most important feature.

If there are other known features that are more important, they would have taken off by now.

[vinceguidry]

You could, ya know, just write code that's easy to understand.

[krapp]

I try to, but that's beside the point. What passes for 'easy to understand' when you move past 'flat text files as a representation of code' and how is it better?

[vinceguidry]

Good naming practice. Either pull each line of non-trivial code out into it's own method, or assign the output of the code to a variable that tells you what it's doing.

If you find yourself repeating an assignment, pull it out into a function and remove the duplication.

Rinse and repeat until everything in the file is assigned to a descriptive function or variable. Doing this with someone else's code gives you a feel for how to do it with your own.

[jjaredsimpson]

This a total non sequitur. What does this have to do with alternatives file formats for code?

[NAFV_P]

> Because we're stuck in a tyranny of flat text files as a representation of code.

Their simplicity is also a strength. That richer file format will at some point be written in a text file.

[Edmond]

Take a look: http://jsfiddle.net/7qZVQ/ Code wrapped in a json formatted meta-wrapper.

I am the founder of Crudzilla Software (see profile for link) a web dev platform.

We use jsr-223 which allows scripting engines for other languages to be integrated into the jvm. What we did was create a file format that serves as a meta-wrapper around pieces of code, we call this wrapper a "crud".

This turns out to be quite powerful as it allows the code to have additional instructions associated with it. For instance input validation, security and configuration can be specified along with the code they apply to.

[vezzy-fnord]

There's nothing wrong with text files.

Although Smalltalk imaging systems are an interesting alternative.

[bergie]

We're trying to address that in the flow-based programming community: http://bergie.iki.fi/blog/noflo-kickstarter-launch/

Freeing code from the constraints of text files would allow different ways to interact with it. Visual programming, REPLs, etc, could work more smoothly in the same workflow as a traditional text editor.

[mattlutze]

- The developer is usually the best person to write down the reasons a line was written. - It's quicker to add an inline note than to switch context to a documentation panel. - It's more complex to have to link a line to a documentation blob as in the example. - A lot of people don't use IDEs; something like that would be necessary given the lower-level work that would need to go on with timestamping and linking code and documentation bits.

"Good enough" principles make inline comments a clear choice, I'd think. Plus, seeing the comment in context may provide cognitive benefits; the comment and code block grouped in the same space helps recognize and associate their linkage in a way cross-highlighting one or the other may not.

[nollidge]

The only way I see this getting any traction is if some wildly popular editor (Emacs?) implements it as a built-in, braindead-simple feature. Then users will start to demand it of other editors.

[rfnslyr]

This would be an absolute godsend.