Tariq Ali is an aspiring web developer dedicated to producing interesting applications and websites for businesses. Before entering into web development, Tariq served as a journalist, real estate a...
I feel disappointed in this article, as I thought it would be about writing a program that takes an AST of your code as input and then outputs literate "pseudocode" that a human can read. For example, if you were to write some FizzBuzz code and feed it into the machine, you would then get the following info:
Set the variable "integer" to equal the input.
Check if "integer" is the modulo of 3, if it is return "fizz".
Check if "integer" is the modulo of 5, if it is return "buzz".
Check if "integer" is the modulo of 3 and the modulo of 5, if it is return "fizzbuzz".
Return "integer".
It might not be good documentation, but it would be interesting documentation.
As for your broader point, I tend to lean towards "Readme Driven Development" - writing the documentation first and then writing the code to match your documentation. You start off with your clean, awesome documentation (knowing what your code is supposed to do beforehand)...meaning you can then focus your time on writing the clean code that matches what your documentation promises.
Also you can add some automation to this:
For example, if you added a change in README, you can say in the description "New Issue: thing X is not implemented, does not match readme", and a git bot that I made will automatically create an issue based on that. Here's a commit and an issue: github.com/ScalaWilliam/git-work/c...github.com/ScalaWilliam/git-work/i...
Side note:
The fizz buzz example is that of imperative code, it's really better to read the code in that case. Where I'm thinking some sort of visual would be useful is in generating a code architecture view automatically. Like a dependency tree within your code.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I feel disappointed in this article, as I thought it would be about writing a program that takes an AST of your code as input and then outputs literate "pseudocode" that a human can read. For example, if you were to write some FizzBuzz code and feed it into the machine, you would then get the following info:
It might not be good documentation, but it would be interesting documentation.
As for your broader point, I tend to lean towards "Readme Driven Development" - writing the documentation first and then writing the code to match your documentation. You start off with your clean, awesome documentation (knowing what your code is supposed to do beforehand)...meaning you can then focus your time on writing the clean code that matches what your documentation promises.
It could also be "bug driven development". Your README is a specification, and you never do anything that is NOT in the documentation first.
I took this approach in my project here: github.com/ScalaWilliam/eventsourc...
Also you can add some automation to this:
For example, if you added a change in README, you can say in the description "New Issue: thing X is not implemented, does not match readme", and a git bot that I made will automatically create an issue based on that. Here's a commit and an issue:
github.com/ScalaWilliam/git-work/c... github.com/ScalaWilliam/git-work/i...
Side note:
The fizz buzz example is that of imperative code, it's really better to read the code in that case. Where I'm thinking some sort of visual would be useful is in generating a code architecture view automatically. Like a dependency tree within your code.