6 ms·

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

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 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 13y ago
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.
- deleted 13y ago
  [deleted]
- krapp 13y ago
  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 13y ago
    I can make a file format as tool-agnostic as you like, if it doesn't actually have to have any features.
    - Crito 13y ago
      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 13y ago
    You could, ya know, just write code that's easy to understand.
    - krapp 13y ago
      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 13y ago
        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 13y ago
        This a total non sequitur. What does this have to do with alternatives file formats for code?
        vinceguidry 13y ago
        What do alternative file formats for code have to do with readability?
        krapp 13y ago
        At the moment I can open up source code in almost any language up in any text editor. It just has to know the encoding and vomit out characters I can comprehend and get the line breaks right. I can print it out and have a hard copy which represents what was written by the programmer. Send it and receive it by email and read it. Code which can be represented as plaintext is versatile and portable and, more importantly, has its comprehensibility decoupled from any specific company, or project or group providing the necessary tools to make it human-readable. If an alternative file format isn't natively human-readable then it is by my definition less readable regardless of the standards put into writing the code itself.
- Edmond 13y ago
  Take a look: http://jsfiddle.net/7qZVQ/ 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.
- NAFV_P 13y ago
  > 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.
- vezzy-fnord 13y ago
  There's nothing wrong with text files. Although Smalltalk imaging systems are an interesting alternative.
- bergie 13y ago
  We're trying to address that in the flow-based programming community: http://bergie.iki.fi/blog/noflo-kickstarter-launch/ 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 13y ago
- 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.
rfnslyr 13y ago
This would be an absolute godsend.
nollidge 13y ago
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.

shalmanese 13y ago

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.

deleted 13y ago
[deleted]
krapp 13y ago
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 13y ago
  I can make a file format as tool-agnostic as you like, if it doesn't actually have to have any features.
  - Crito 13y ago
    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 13y ago
  You could, ya know, just write code that's easy to understand.
  - krapp 13y ago
    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 13y ago
      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 13y ago
        This a total non sequitur. What does this have to do with alternatives file formats for code?
        vinceguidry 13y ago
        What do alternative file formats for code have to do with readability?
        krapp 13y ago
        At the moment I can open up source code in almost any language up in any text editor. It just has to know the encoding and vomit out characters I can comprehend and get the line breaks right. I can print it out and have a hard copy which represents what was written by the programmer. Send it and receive it by email and read it. Code which can be represented as plaintext is versatile and portable and, more importantly, has its comprehensibility decoupled from any specific company, or project or group providing the necessary tools to make it human-readable. If an alternative file format isn't natively human-readable then it is by my definition less readable regardless of the standards put into writing the code itself.
Edmond 13y ago
Take a look: http://jsfiddle.net/7qZVQ/ 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.
NAFV_P 13y ago
> 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.
vezzy-fnord 13y ago
There's nothing wrong with text files. Although Smalltalk imaging systems are an interesting alternative.
bergie 13y ago
We're trying to address that in the flow-based programming community: http://bergie.iki.fi/blog/noflo-kickstarter-launch/ 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 13y ago

- 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.

rfnslyr 13y ago

This would be an absolute godsend.

nollidge 13y ago

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.