Print Page - How do you maintain your code?

Programming => General => Topic started by: TBMan on January 21, 2025, 06:10:56 pm

Title: How do you maintain your code?
Post by: TBMan on January 21, 2025, 06:10:56 pm

I try to do the following for all of my projects that I'm coding. It really helps when I'm debugging and trying to trace a problem. When I go back to
look at code I wrote 30 years ago I shake my head and wonder why I didn't leave myself a road map. I don't use a lot of comments in my code
as I try to write with the intent being clear by how I name my procedures, functions and variables. I'm thinking though maybe a bit more commenting in my code could be helpful.

Here's my "content header" for the sprite editor that I'm working on. Naming the section allows me to search for the section easily.

Code: Pascal [Select][+]

{
  SprEd - sprite editor  Started 1/20/25
  Edits up to 20x20 sprites. Can be made to go with
  bigger sprites if the graph mode size is increased.
  It is currently using 800x600
 
1/20/25
  Started project
  Got up to the width/depth dialog box, but without
  the width bottons and with no functionality.
 
1/21/25
  Finished width/depth dialog, fully functional
 
******************************
 Section0 Initilization
******************************
 Procedure InitProgram;
 Procedure InitialGrid;
******************************
 
******************************
  Section1 Grid maintenance
******************************
Procedure SetRectPositions(GridDepth,GridWidth:integer);
Procedure drawGrid(Depth,width:integer);
Procedure SetColorGrid;
Procedure drawColorGrid;
Procedure ClearGrid(depth,width:integer);
Procedure DrawSpriteGrid(s:lg_spriteclass);
 
 
*************************************
Section2 Push button Event management
*************************************
Procedure CheckGrid(Wx,Wy:longint);
Procedure GetColor(Wx,Wy:Longint);
Procedure SaveSprite; fixed file name for now
procedure LoadSprite; fixed file name for now
Procedure Export;
 
*********************************************
Section3 Graphics and function of pushbuttons
*********************************************
Procedure DrawButtonUp(Item:Integer);
Procedure DrawButtonDown(Item:Integer);
Procedure AddButton(x,y,xx,yy:integer;Id:Integer;Ts:string);
Procedure MenuButtons; (Initializes all of the menu buttons)
 
*********************************************
Section4 Graphics and function of checkboxes
*********************************************
Procedure DrawCheckBox(CheckBox:CheckBoxType);
Procedure AddDepthCheckBox(x,y,Id:integer;Ts:String;default:boolean);
Procedure AddWidthCheckBox(x,y,Id:integer;Ts:String;default:boolean);
Procedure ChangeSize;   (Executes the Change size dialog with local event handler)
}
                               

Title: Re: How do you maintain your code?
Post by: cdbc on January 21, 2025, 06:21:11 pm

Hi
I do it like this (https://gitlab.com/cdbc-public/icontainers) and sometimes I comment more, but never less... ;D
Regards Benny

Title: Re: How do you maintain your code?
Post by: Martin_fr on January 21, 2025, 06:44:19 pm

As for the "changelog" => what was added/changed when and in which order: I use git.

Even on private projects, even on small projects. I can always create a local git repository in the project folder (no remote needed).
If I want a backup, remote to either a different disk, or to a private repo at one of the common hosts. (Or a remote computer of my own, if the source must stay 100% private)

The advantage is, that not only can I see what (and why) I have done, but
- I can also see each line that changed, and how it changed
- I can search at what time a line was last changed (search by line, instead by time / blame)
- I can undo (for testing) any change I made and go back to any previous version
- I can do micro commits (every few minutes) while making changes, once they work I rebase them into just one commit (never again, I broke 5 hours of work in the last 5 minutes and don't know exactly where)
- I can keep "gone wrong" attempts in a branch in case I want to use any part of them later.

Title: Re: How do you maintain your code?
Post by: MarkMLl on January 21, 2025, 06:52:10 pm

Subversion locally (iff doing something collaborative I'd consider Git). A large number of carefully-phrased comments. A .project file in each main directory which tells me where I'm at.

MarkMLl

Title: Re: How do you maintain your code?
Post by: 440bx on January 21, 2025, 07:45:59 pm

One thing I learned the hard way is that what often seems to be totally obvious when writing the code is rarely obvious just a few months later.

My solution is to comment the code as if I were writing the program as a tutorial for an intermediate level programmer (IOW, some basic stuff isn't explained.) This means a totally _lavish_ number of comments that _explain_ the "big picture" and how it is going to be implemented.

For non throw-away programs, I pay particular attention to the structure of the program. I want the mainline to reflect the _entire_ program structure, This is a bit hard to explain but, if a program consists of 50 logical steps then there should be a function/procedure that consists of 50 steps, ideally properly commented.

The other thing I have found extremely useful in the maintenance of code is to associate a particular test case with a particular sequence of code. This way you know why the code is there and what problem it solves. For instance, imagine you're implementing a dis-assembler (which needs to find and process many binary patterns), it's good to place a comment such as:

Code: Pascal [Select][+]

{ case found AcGenral.x32.dll cookie and scope record information after a ret }
{                                                                                                                            }
{ 755E22C8 E8 73 00 00 00                                               call    __SEH_epilog4                                }
{ 755E22CD C2 0C 00                                                     retn    0Ch                                          }
{ 755E22CD                                                                                                                   }
{ 755E22D0 FE FF FF FF 00 00 00 00 D4 FF FF FF 00 00 00+stru_755E22D0   dd 0FFFFFFFEh           ; GSCookieOffset             }
{ 755E22D0 00 FE FF FF FF 74 97 5E 75 85 97 5E 75 FE FF+                                                                     }
{ 755E22D0 FF FF 8F 97 5E 75 A0 97 5E 75 FE FF FF FF B0+                dd 0                    ; GSCookieXOROffset          }
{ 755E22D0 97 5E 75 C1 97 5E 75 FE FF FF FF E7 97 5E 75+                dd 0FFFFFFD4h           ; EHCookieOffset             }
{ 755E22D0 F8 97 5E 75 FE FF FF FF 19 98 5E 75 2A 98 5E+                dd 0                    ; EHCookieXOROffset          }
{                                                                                                                            }
{ 755E22D0 75 FE FF FF FF 58 98 5E 75 69 98 5E 75 FE FF+                dd 0FFFFFFFEh           ; ScopeRecord.EnclosingLevel }
{ 755E22D0 FF FF 79 98 5E 75 8A 98 5E 75 FE FF FF FF C3+                dd offset loc_755E9774  ; ScopeRecord.FilterFunc     }
{ 755E22D0 98 5E 75 D4 98 5E 75                                         dd offset loc_755E9785  ; ScopeRecord.HandlerFunc    }
{ 755E22D0                                                              dd 0FFFFFFFEh           ; ScopeRecord.EnclosingLevel }
{ 755E22D0                                                              dd offset loc_755E978F  ; ScopeRecord.FilterFunc     }
{ 755E22D0                                                              dd offset loc_755E97A0  ; ScopeRecord.HandlerFunc    }
{ 755E22D0                                                              dd 0FFFFFFFEh           ; ScopeRecord.EnclosingLevel }
{ 755E22D0                                                              dd offset loc_755E97B0  ; ScopeRecord.FilterFunc     }
{ 755E22D0                                                              dd offset loc_755E97C1  ; ScopeRecord.HandlerFunc    }
{ 755E22D0                                                              dd 0FFFFFFFEh           ; ScopeRecord.EnclosingLevel }
{ 755E22D0                                                              dd offset loc_755E97E7  ; ScopeRecord.FilterFunc     }
{ 755E22D0                                                              dd offset loc_755E97F8  ; ScopeRecord.HandlerFunc    }
{ 755E22D0                                                              dd 0FFFFFFFEh           ; ScopeRecord.EnclosingLevel }
{ 755E22D0                                                              dd offset loc_755E9819  ; ScopeRecord.FilterFunc     }
{ 755E22D0                                                              dd offset loc_755E982A  ; ScopeRecord.HandlerFunc    }
{ 755E22D0                                                              dd 0FFFFFFFEh           ; ScopeRecord.EnclosingLevel }
{ 755E22D0                                                              dd offset loc_755E9858  ; ScopeRecord.FilterFunc     }
{ 755E22D0                                                              dd offset loc_755E9869  ; ScopeRecord.HandlerFunc    }
{ 755E22D0                                                              dd 0FFFFFFFEh           ; ScopeRecord.EnclosingLevel }
{ 755E22D0                                                              dd offset loc_755E9879  ; ScopeRecord.FilterFunc     }
{ 755E22D0                                                              dd offset loc_755E988A  ; ScopeRecord.HandlerFunc    }
{ 755E22D0                                                              dd 0FFFFFFFEh           ; ScopeRecord.EnclosingLevel }
{ 755E22D0                                                              dd offset loc_755E98C3  ; ScopeRecord.FilterFunc     }
{ 755E22D0                                                              dd offset loc_755E98D4  ; ScopeRecord.HandlerFunc    }
{ 755E2340                                                                                                                   }
{ 755E2340 8B 4D F0                                                     mov     ecx, [ebp-10h]                               }
{ 755E2343 64 89 0D 00 00 00 00                                         mov     large fs:0, ecx                              }
{ 755E234A 59                                                           pop     ecx                                          }
 
 

above the code that takes care of detecting and handling that pattern.

Another important characteristic of a well written program is that every path is individually tested during development. One method that is quite useful is to force if statements to execute an empty statement thereby forcing the code that is normally conditionally executed to execute. Here is what I mean:

Code: Pascal [Select][+]

if <some condition> then
  {$if defined test_some_condition} ; {$endif}
begin
  < statements executed when "some condition" is true >
end;
 

This way, all you need to do to figure out if the statements deal with the condition correctly is to define "test_some_condition".

As a consequence of the above, there should be one include file in the project that list _every single one_ of these cases along with an informative comment giving details of what is being tested and what the intended result of the test is expected to be.

Another thing that makes a substantial difference after a few months (or a few years) is to have hard coded breakpoints that are conditionally executed in the code. Those breakpoints should exists in places that are _important_, for instance, if an assert condition fails during testing and development. Also convenient is to place them in important/critical functions. For instance, using the dis-assembly example, imagine there is a function that scans and detects int 3 sequences (compilers commonly generate those for one reason or another), the dis-assembler can have a set of defines such as:

Code: Pascal [Select][+]

{$define BREAK_ScanForInt3sequences_Enter}
 
  {$define BREAK_ScanForInt3sequences_AddressValue}
  {$define BREAK_ScanForInt3sequences_ScanAbandoned}
 
  {$define BREAK_ScanForInt3sequences_Int3IsJmpArgument}
 
  {$define BREAK_ScanForInt3sequences_Int3InAddress}
 
{$define BREAK_ScanForInt3sequences_Exit}

activating the first define causes a break when the function is entered. The indented defines are additional breakpoints in the function that are triggered only when specific cases occur.

That way, it's easy to "reload" in your mind what the function does.

A "corollary" of all this is that a good debugger is an _essential_ tool in the analysis and maintenance of a program.

Those are just a few things (less than 10%) about writing maintainable code. It is very, very rare to find a program that is written with maintainability in mind. It's amazing some programs can be maintained at all. What's _not_ amazing is the presence of bugs in them (because often code is added or modified with only a _partial_ understanding of how the code work (presuming it works at all.)

For a lot of programmers, the above is way too much work. IMO, that reflects how "valuable" the code is.

For the record, many decades ago, I spent about 5 years developing an algorithm to solve a problem. It was pure research. I threw code at the computer for 5+ years and one day, lo and behold, I found the solution to the problem (to this day, it's only known solution to the problem), I was ecstatic, wearing a smile from ear to ear.

Now the sad part, I never commented any of the algorithms in the program because I didn't know if they were part of the solution of not and it didn't cross my mind that I would forget how the solution works.

Every algorithm was just "another thing to try". To make a long story short, the program consists of hundreds of different algorithms, a _subset_ of them, executed in a _specific_ sequence, solves the problem. Now the problem is, I eventually _forgot_ which functions and their sequence solve the problem and, since there are no comments, I'd have to figure it out all over again (it wouldn't take 5 years but, it would still be a fair amount of time.)

As a result of that, now, every program that is of intermediate complexity or above, I write it as a tutorial to myself. Now, I can look at code I wrote 15 years ago and, usually, in less than 30 minutes I have the whole thing back in my mind.

HTH.

Title: Re: How do you maintain your code?
Post by: lainz on January 21, 2025, 08:13:35 pm

That shows a bit of how old are you If you coded more than 15 years...

I personally use git, and is a time saver when finding bugs, because one can search the logs and find specifically modified files in a timeline. To see if a change was made or not, possible bug sources...

Title: Re: How do you maintain your code?
Post by: 440bx on January 21, 2025, 08:20:25 pm

Quote from: lainz on January 21, 2025, 08:13:35 pm

That shows a bit of how old are you If you coded more than 15 years...

I've been coding for 48 years... I started young... live and learn (sometimes the easy way and sometimes the hard way... oh well.)

Title: Re: How do you maintain your code?
Post by: lainz on January 21, 2025, 08:23:38 pm

Quote from: 440bx on January 21, 2025, 08:20:25 pm

Quote from: lainz on January 21, 2025, 08:13:35 pm
That shows a bit of how old are you If you coded more than 15 years...
I've been coding for 48 years... I started young... live and learn (sometimes the easy way and sometimes the hard way... oh well.)

You coded for more years than my actual age, 35, I started coding at 17, but in a company since 2018.

Title: Re: How do you maintain your code?
Post by: MarkMLl on January 21, 2025, 09:20:55 pm

Quote from: 440bx on January 21, 2025, 08:20:25 pm

I've been coding for 48 years... I started young... live and learn (sometimes the easy way and sometimes the hard way... oh well.)

48 or 49... sounds about right if you include my student FORTRAN.

Fun fact: on the day I joined Burroughs, the site to which I was told to report was upgrading its mainframe from core to semiconductor memory.

MarkMLl

Title: Re: How do you maintain your code?
Post by: dbannon on January 22, 2025, 01:23:24 am

Quote from: MarkMLl on January 21, 2025, 09:20:55 pm

Fun fact: on the day I joined Burroughs, the site to which I was told to report was upgrading its mainframe from core to semiconductor memory.

semiconductor memory ? Just a passing fad. At least with magcore, you can see where your data is being kept !

Davo

Title: Re: How do you maintain your code?
Post by: Wesbat on January 22, 2025, 09:03:46 am

For the past year I decided to try write more idiomatic code: break large pieces of work into smaller routines, each has its own job. I name them sensibly to describe their function. This negates the need for comments most of the time.

There are always exceptions. If a routine can't be reduced to simplicity then I add comments to demarcate notable logic, I try describe why something is done this way, not just what is happening.

On the back-end I use git locally. Been writing code for 30 years. Magic times!

Title: Re: How do you maintain your code?
Post by: Martin_fr on January 22, 2025, 12:21:29 pm

About documentation and comments.

"assert" is a good way to do that.

It may not be as verbose as a whole paragraph of comment, but it can still be quite verbose. The good thing however is, it protects itself from being outdated. That is, assuming the code is regularly run with assertions enabled. And, if needed, there can be whole blocks/groups of asserts.

Also it is a slightly different way of documentation.

Code: Pascal [Select][+]

assert(SearchIdx>LastResult, 'Function-Name: SearchIdx>LastResult / Description why that must be');

Does give 2 vital bits of info.

1) Any further use of SearchIdx is safe. If I placed the assert there, then I have checked (considering all possible code-paths that could lead to this line) that the condition must be true. The assert documents this. I can read any code below this, with the knowledge, that the code above does ensure this.

2) Whatever I put in the description. If I added description.

If the code changes, so the condition does not hold any more, then I am forced to update it. Had that just been a comment, it might be overlooked and become false info.

Lazarus

Programming => General => Topic started by: TBMan on January 21, 2025, 06:10:56 pm