The first fun little spin-off of the revived Vera project may come to you in an unexpected form: assembly coding standards and proper code documentation.
As you may all be aware, keeping source organized is not something the TI community is especially keen on. In fact, many people just produce "write-once-and-never-try-to-read-again" code that only they can understand (and only for the duration of the project) and afterwards the code will get lost on some harddrive anyway.
There are several more experienced programmers in the scene though, who have discovered that jotting down a few pre- and postconditions (and perhaps even something about the internal logic) in the comments of a routine really IS worth those few minutes of your time, as it will save you countless headaches as the project grows larger and harder to maintain. Diederik Kingma (Duck) was one of the first people I saw doing this in his greyscale programming package, though of course I couldn't have been looking at everyone's source. These experienced programmers all have their own ways of noting this metadata though, and usually it is still only meant to be read by themselves as it is mostly quite minimalistic.
Duck's GPP showed clearly in which circumstance having well documented code is absolutely necessary: in the case where you're releasing a library and you hope others will find it beneficial and want to interface with it. I was one of the first people to integrate his library into a game we were back then working on, and thanks to his easy to read comments and good documentation we didn't just manage to implement greyscale in our game (which was about 30k and quite complex) in just a few days, we also managed to track down a few interrupt related bugs in the Ti-83 specific code that we ran into. Through Ticalc.org I came in contact with Duck, I reported the bugs we had found, he introduced me on MaxCoderz, and the rest is history.
Later, having worked with javadoc a bit in college, and realizing the ease of generating documentation from your comments, I tried to standardize the headers above routines and in file descriptions among assembly programmers by providing a web-based asmdoc tool that would accept a few tags and turn your source into HTML output. It wasn't very popular though, partly because people didn't care or see any purpose in it, partly because of the limited use of a web-based application for this, and probably partly because of the poor implementation (only one file at a time, no proper export...).
Vincent (KV) did see the point in generating documentation though, and when he tried to set up a database of often used assembly snippets (the codebank), he contacted me to integrate it with my asmdoc tool, or something similar. As so often with ambitious projects, in the end it turned out we didn't have the time to finish it. It did however spark my API, which combined the code snipped database idea with an easy to use macro system (so you wouldn't have to go back to the website for every new snippet) as well as the automatically generated asmdoc idea.
Ben also got interested in automatic documentation from comments when he was working on Latenite and Brass, and together we tried to come up with a simple and easy to use "protocol" for documenting assembly code. However, we tried to make it kinda backwards compatible with existing source, and unintrusive to the user, which turned out to be impossible, and the attempt was postponed.
Now, almost five years after reading through Duck's code, it seems we're finally nearing both a good and simple asmdoc-protocol and the tools to generate documentation from it, thanks to the Vera project.
The typical trends of throw-away-code are exactly the opposite of what the Vera project is aiming for: fairly modular, easy to read and understand code that many people have to be able to work on, and that can be a learning experience for newcomers as well as a tool for research and play for the old farts. Vera has to be transparent. People have to be able to write applications against our API. This is why we have started to draw up some coding standards for this project.
As we were working on that, Ben wrote to the mailing list:
So we started designing that standard, finally finishing what we started years ago, and we've now come to the point where we have a coding standard for routine headers that is both easily human readable and parsable by software.We could use this as an opportunity to (finally!) decide on a comment documentation standard. A parser that can rip out the comments and produce some nice HTML pages (and a CHM) would be relatively easy to write and would aid developers (who really wants to trawl through tons of source code?)
You can find the Vera coding standard on our wiki here:
http://timendus.student.utwente.nl/~ver ... _standards
(Please remember that it is still in development though, and that it could be subject to change at any time. However, no major changes are expected in the foreseeable future.)
In addition to that, both ElfPrince and I have been implementing two seperate comment parsers aimed at these standards, which are nearing usefulness. A bit of healthy competition has made sure that after just a week we have two almost done parsers that we will probably release to the public some time soon. This is our test assembly source (you'd best view the coding standards on the wiki first)...:
Code: Select all
;; Vera - the calc lover's OS,
;; copyright (C) 2007 The Vera Development Team.
;;
;; This is a test assembly file to test the reference implementation
;; asmdoc tool.
;
; This program is free software: you can redistribute it and/or modify
; it under the terms of the GNU General Public License as published by
; the Free Software Foundation, either version 3 of the License, or
; (at your option) any later version.
;
; This program is distributed in the hope that it will be useful,
; but WITHOUT ANY WARRANTY; without even the implied warranty of
; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
; GNU General Public License for more details.
;
; You should have received a copy of the GNU General Public License
; along with this program. If not, see <http://www.gnu.org/licenses/>.
; ===================
; We'll put in a fake console routine here
;; === console.printline ===
;;
;; Print a null terminated string to the display
;; using some crappy display port writes
;;
;; Don't use it too often, it'll fry your screen :-)
;;
;; Pre:
;; hl = pointer to string
;;
;; Post:
;; String displayed on screen
;; hl,bc,a destroyed
;;
;; SeeAlso:
;; console.putchar, console.set_cursor_x, console.set_cursor_y
;;
;; Warning:
;; Do not call this function if you have manually
;; set console_cursor_x or console_cursor_y outside
;; the console boundaries.
;;
;; Example:
;; ld hl,str_welcome
;; call console.printline
;; ret
;; str_welcome:
;; .db "Welcome to Vera",0
console.printline:
ret
;; === console.newline ===
;;
;; Print a newline to the console
;;
;; Post:
;; Updated cursor position, scrolled screen if necessary
;; hl,a destroyed
;;
;; SeeAlso:
;; console.printline, console.set_cursor_x, console.set_cursor_y
;;
;; Example:
;; call console.newline
console.newline:
ret
; === console.putchar ===
;
; Internally used routine, just one semicolon
;
; Pre:
; a = character
;
; Post:
; Character put on display
; hl,a destroyed
;
; SeeAlso:
; console.printline
;
; Example:
; ld a,'F'
; call console.putchar
console.putchar:
ret
; ===================
; End of file
; ===================
Or see for yourself here:
http://timendus.student.utwente.nl/~vera/asmdoc/
(Opera incompatibility is a known bug)
I'm quite sure ElfPrince will quickly post a screeny of his own output (I can't get your script to run as well as I would like, and I don't want to give myself an unfair advantage)
It almost seems like programming in assembly for calculators is finally growing up just a little bit
Edit: I've released the first public version of my tool, see this post.