Re: Crap 0.1 first assembly project
Posted: Mon Feb 05, 2018 7:51 am
Day 36: 329 days left
It's day 36 and I just got to the stage where documentation is at a good place. After having a gentle critique that my code was a little bit on the 'WTF is this? what is it doing?' side of the spectrum. (I recalled in college winning an award for obscure C coding.. I kept that mars bar for years after )
I figured that my current approach of using a wiki was going nowhere fast as frankly I am too lazy to update it. What I wanted was a way that I could write the code at the same time as waxing lyrical about it in the source .. have that source then either compile/assemble/run in an interpreter when I wanted it too or when I needed to read it, use a markdown viewer to show all the information about what the code was doing, along with the code it was talking about.
In a nutshell... literate programming.
To be honest at first when this was explained to me I just though 'ahh sounds like some sort of chin scratcher crap.' but I thought "well give it a go, its got to be better than what your doing now.." and to my suprise it is.
The script is just a humble awk script called blaze. If that wank word / programming wuwu offended you as much as it did me. Then you are on the same page as I was with regards to this.. At this point I nearly clicked off in disgust but thinking that this literate programming stuff might have some merit I stuck with it and turned the other cheek.
Still its the ends not the means .. What this enables me to do is put all of the explanation, ideas and stuff into the actual source document. That way when I forget everything about it then have to come back and try and fix it I just look at the source in a markdown viewer and badabing badabomb I or whoever is handling my estate is going to be able to maintain whatever mess is left of my programming output.
The nice thing about this is because its markdown, most everyone knows how to write it. You can include images, videos, audio whatever takes your fancy. The source now explains the program. Giving the reader the ability to maintain it. It's not documentation - that is something else. The user manual could probably use a good portion of what is inside the source comments but that is a different thing for a different application (teaching people about the application to be able to use it... not to maintain/upgrade it.) I think that is what got me confused at the beginning.
Anyway - this is how the projects are really going to get commented. Hopefully this will make explaining what I am doing in crap-chess much easier and in the noughts and crosses game.
To test this I will use the technique on Noughts and Crosses and see how it goes today.
It's day 36 and I just got to the stage where documentation is at a good place. After having a gentle critique that my code was a little bit on the 'WTF is this? what is it doing?' side of the spectrum. (I recalled in college winning an award for obscure C coding.. I kept that mars bar for years after )
I figured that my current approach of using a wiki was going nowhere fast as frankly I am too lazy to update it. What I wanted was a way that I could write the code at the same time as waxing lyrical about it in the source .. have that source then either compile/assemble/run in an interpreter when I wanted it too or when I needed to read it, use a markdown viewer to show all the information about what the code was doing, along with the code it was talking about.
In a nutshell... literate programming.
To be honest at first when this was explained to me I just though 'ahh sounds like some sort of chin scratcher crap.' but I thought "well give it a go, its got to be better than what your doing now.." and to my suprise it is.
The script is just a humble awk script called blaze. If that wank word / programming wuwu offended you as much as it did me. Then you are on the same page as I was with regards to this.. At this point I nearly clicked off in disgust but thinking that this literate programming stuff might have some merit I stuck with it and turned the other cheek.
Still its the ends not the means .. What this enables me to do is put all of the explanation, ideas and stuff into the actual source document. That way when I forget everything about it then have to come back and try and fix it I just look at the source in a markdown viewer and badabing badabomb I or whoever is handling my estate is going to be able to maintain whatever mess is left of my programming output.
The nice thing about this is because its markdown, most everyone knows how to write it. You can include images, videos, audio whatever takes your fancy. The source now explains the program. Giving the reader the ability to maintain it. It's not documentation - that is something else. The user manual could probably use a good portion of what is inside the source comments but that is a different thing for a different application (teaching people about the application to be able to use it... not to maintain/upgrade it.) I think that is what got me confused at the beginning.
Anyway - this is how the projects are really going to get commented. Hopefully this will make explaining what I am doing in crap-chess much easier and in the noughts and crosses game.
To test this I will use the technique on Noughts and Crosses and see how it goes today.