Managing code

[banedon]

Hi guys

How do you guys go about managing your code given how large assembly source code can get? I'm finding that having one massive list is a little off putting nd have thought about using include files.
However, does anyone use an editor that helps split the code into subsections?

[GARTHWILSON]

Macros are enormously valuable for reducing source-code length, making it more intuitive, reducing bugs, reducing development time, improving maintainability, etc., without losing any of the advantages of assembly. I use INCLude files for things like generic macros that might be used in many different projects; but ones that are specific to a project are kept in the main source-code file. In my '816 Forth (which hopefully someday I'll finish the documentation on for publishing), various parts are in INCLude files so for example if someone doesn't want the extended math package, they can easily leave it out.

[scotws]

While we are on the subject, I can't recommend git (https://git-scm.com/) highly enough even for small projects. Being able to quickly branch off some experiment and then be able to say nah, that sucked without any bad side effects and minimal time lost is well worth the learning curve.

[GARTHWILSON]

I've never used git; but I have, many times, made a copy of a source-code file and given it another name, then put comments in the first few lines telling that this file came from that one and then was adapted to do such-and-such differently. When you come back to these later, you won't remember what the different versions were for and why you did them, so it's important to put this info in the comments immediately. I might also have an explanation file in the folder telling the sequence and which file is what.

[Rob Finch]

Usually when code gets to being thousands of lines long I break it up into smaller modules / separate files so I don't spend all my time scrolling around in one massive file trying to find things. Another thing to consider is resetting the location counter occasionally to allow space for code to grow or for fixes. I sometimes use the 'align' keyword to align routines (or vars) on larger than normal boundaries. Eg. align 256 to align on a 256 byte boundary. It helps to keep variable and routine addresses at the same familiar location in assembly listings as other things change.

Quote:

does anyone use an editor that helps split the code into subsections?

If one can find an editor that is adaptable enough to use for custom instruction sets and that accepts user keywords and other definitions. It can help a lot. In the past I've used UltraEdit.

[GARTHWILSON]

I use the MultiEdit professional programmers' text editor which allows having multiple screens into the same file, so you don't have to do such scrolling. You can keep multiple places in the file in view at the same time. You can also have markers to different parts of the file to go back and forth quickly, and these don't affect the file, only the editor's knowledge of parts you want to get to quickly as you jump around. I am not familiar with UltraEdit but it looks really nice too.

[nyef]

My practice (okay, with Lisp code, but I feel similar pressures with Forth, and I don't see why I wouldn't with assembly language) is to start looking at breaking a file up when it hits 512 lines (if not sooner, often 256 lines is more than sufficient for a single, coherent behavior/function, and I like separating functional areas into separate files where possible), and it getting to be a fairly high priority when it hits 1024 lines. This might run the "risk" of becoming RavioliCode, but I haven't noticed any major trouble with it yet.

Also, I'll second the recommendation of git. For basic stand-alone usage, the learning curve is measured in minutes. You basically need "git init", "git add", "git commit", "git diff", "git log", "git branch", "git checkout", and occasionally "git reset" (though I often use "git diff | patch -Rp1" instead). "git stash" is useful, but not immediately necessary. For that matter, you can easily "get away" without log, branch, checkout, or reset for a while. I seem to keep projects outside of source control for far too long before I finally create a git repository for them, and once I do I have a lot more freedom to just try things, and either leave them on a branch, revert them, or whatever. Something I hope to work on in the future (possibly to the point of doing a "git init" before even laying down any code). The ability to see "here's what I changed from the last working version" alone is worth the price of entry, nevermind having a full history of changes, the ability to leave various experiments on branches, bisection search to find where some behavior changed, various collaboration options... At the very least, spend the half-hour or so it takes to get minimally familiar with it. The worst case scenario is that you've wasted half an hour. The best case scenario is that you have a powerful new tool in your toolbelt (not your toolkit, your toolbelt is closer to hand, and easier to navigate by instinct than your toolkit).

[BigDumbDinosaur]

banedon wrote:

Hi guys

How do you guys go about managing your code given how large assembly source code can get? I'm finding that having one massive list is a little off putting nd have thought about using include files.
However, does anyone use an editor that helps split the code into subsections?

I use INCLUDE files to keep the overall project manageable. See the attached file for how I organized the firmware source code for POC V1.1, which has over 12,000 lines en toto. During program editing I open multiple windows so I can have several source files simultaneously loaded. That makes it convenient to work on several sections of a large program at the same time.

pocrom.asm

POC V1.1 Firmware Root Source File

(24.54 KiB) Downloaded 120 times

[Tor]

I too recommend Git. After I started using it years ago I now basically don't keep any information around without entering it into Git.. the computer configuration files, my updated inventory lists of components and parts, all those small software tools (and that's where the experimental branching is used). If it's not in Git I consider it extremely volatile.

-Tor

[BigEd]

There's also the question of publishing code. If you use a source control system there's probably a free web service somewhere which will publish it for you: that serves as a public archive and also a place to convene for joint efforts. In the case of git, github is the place to be: they also provide a wiki and an issue tracker for each project (you can have multiple projects.) Indeed, they provide a means of hosting, which is handy for a blog or for a live version of a JavaScript project. All for free.

(For example, http://skilldrick.github.io/easy6502/ is a live site, https://github.com/skilldrick/easy6502 is the project's code and documentation, and I have my own fork of the project. In this case we haven't made use of the wiki. Another example is 6502js where my fork actually has some different development and a live site was exactly what I needed.)

One big advantage of git is that every working copy of the project is standalone and complete: if I lose my copy, github has it, and if github shuts down, my copy is still fine. If you take a fork, it will survive if I delete mine. If I've worked on a project on two computers, I have two complete and independent copies. (Reconciling any differences is one of git's fundamental strengths.)

[Bregalad]

I presonally use of course multiple backups levels. First I regularly copy important source files to their equivalent, so that I have both source.asm and source.bak.
Then I copy the whole folder somewhere else regularly, and copy it to as many different computers/USB keys as possible, but I have the "main" version always at the same place so that I know which one is the latest (the same place is on the hard disk of my main computer).

Using this strategy I am able to get a lot of back ups at strategic times, so that if anything goes wrong I am sure that I have an old version under the hand (the .bak file), and if I have a hard disk failure or anther serious issue, I get the backup from another drive (including the .bak file).

I do not use git or other things, I am worried about their privacy, and they are extremely hard to use anyway. They sure are worthy if more than 1 people is working on the project, there's no doubt.

[BitWise]

I write most of my assembler code using relocatable macro assemblers (including my own) so I break it up into modules by function and use a makefile to assemble files affected by changes and link them together.

I have a NAS box for backups which I installed the Linux subversion server on and create separate project repository areas for everything I'm working on. I use Tortoise SVN on my Windows PCs to update from and commit to the repositories. I synchronise files between development PCs via the repository.

Some of my open source code has been moved to GIT based repositories in response to Google's planned closure of its public code repository.

GIT suits the open source world well as it allows developers to have local copies of the repository that they can commit to without having to push changes back to the original source but I prefer SVN for small personal projects.

[White Flame]

One thing I'm careful to do is to try to keep files order-independent. The ca65 assembler is quite powerful in terms of its segments and linker, and if you use it carefully you don't have to worry as much about implicit cross-file dependencies.

Git here as well, recommended for small personal projects.

[BigDumbDinosaur]

White Flame wrote:

One thing I'm careful to do is to try to keep files order-independent.

I try to do that as well, but sometimes forward reference issues will force the inclusion of files in a certain order. Also, some 6502 assemblers blithely assume that something is a 16 bit value if it is referred to before being declared. This sort of behavior can occasionally lead to difficult-to-find phase errors. I avoid this by declaring constants and direct (zero) page locations before any code references them.

BigEd wrote:

There's also the question of publishing code.

In that regard, I prefer bundling my code into archives (e.g., ZIP files) for distribution.

[scotws]

GARTHWILSON wrote:

I use the MultiEdit professional programmers' text editor which allows having multiple screens into the same file, so you don't have to do such scrolling.

By blind luck, I started off with vi (now vim http://www.vim.org/) on my very first Unix-y machines decades ago. Few things in my life have been so worth the initial investment of time and effort, though I admit if you are new to the editor, the learning curve is brutal. The power of the thing under the hood is just amazing, with stuff like "multiple screens" ("windows" in vimese) available without a GUI by default, and scripting for about anything else. I spent a few days writing some routines to help with my blogs (shortcuts for including web addresses, HTML insert, etc) and it cut down the time required for formating stuff to less than a tenth. (Of course, I can't make heads of tails of my own scripts any more, but they still work )

Especially if you touch-type and write a lot of, well, anything, I can't recommend vim highly enough.