Trying to make sense of your old code

43 views
Skip to first unread message

Paola Kathuria

unread,
Feb 11, 2022, 2:37:53 PM2/11/22
to PPIG Discuss
I'm curious if there is research on how developers manage to navigate through their old software when they need to make changes to fix bugs.

I'm finding it really heard to remember and understand the 19K of code I wrote nearly four years ago.

It's made me realise how challenging it must be to change and maintain someone else's software, if someone leaves a team, for example.

I developed an online service for me and friends called Tell Me When (TMW) where you tell it what your interests are (genre, actors, directors, specific series) and it lets you know when anything matching turns up in the TV schedule (UK).

I developed it in Drupal 7 with a custom module in PHP (28 files. I have 3 perl and shell scripts.

I get TV schedule data by using APIs from other web sites or scraping the schedule data from web pages (downloading web pages, parsing and extracting structured data).

Over the years, the three sites twice disappear or change their web pages, breaking TMW. I have to then get deep into the code and try to understand the import and parsing software I wrote, which is fairly complex. I honestly feel as if I am stumbling around in semi-darkness.

Yes, meaningful function names, variable names and comments help, but I don't really have a sense any more of how it all hangs together. I am concerned that I my changes are making things more complex as a result.

I am not really sure what I am asking, but I wondered if anyone else recognises what I am talking about and how they manage.

Finally, if you've read this far and would like to see/use TMW (it's free), let me know and I'll send you more information.


Paola

Peter Hornsby

unread,
Feb 11, 2022, 2:43:56 PM2/11/22
to Paola Kathuria, PPIG Discuss
I think the phrase is "Document your code as if the next person to maintain it is a violent sociopath who knows where you live"! 

I'm not aware of research into how, but the effort put into teaching devs to document their code (and the documentation generators etc. that support this) suggest the problem is widely acknowledged. 

P

--
You received this message because you are subscribed to the Google Groups "PPIG Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ppig-discuss...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/ppig-discuss/4b05fed6-f2f0-4a94-83a6-deb086db2b2an%40googlegroups.com.

Paola Kathuria

unread,
Feb 11, 2022, 2:47:36 PM2/11/22
to PPIG Discuss
On Friday, 11 February 2022 at 19:43:56 UTC drpeterhornsby wrote:
I'm not aware of research into how, but the effort put into teaching devs to document their code (and the documentation generators etc. that support this) suggest the problem is widely acknowledged. 

Indeed.

I document functions and specific lines or blocks of code.

For a system that I built for myself that only I will ever touch, how do you suggest I document how 258 functions in 28 program files all fit together, for a meta view? That is the bit I am struggling with.

Paola

Peter Hornsby

unread,
Feb 13, 2022, 6:01:31 AM2/13/22
to Paola Kathuria, PPIG Discuss
I'm sure a more experienced coder could offer better advice, but I'd usually document some of the detail in the code itself, and the broad functionality in a separate document, generally with lots of diagrams!

P

--
You received this message because you are subscribed to the Google Groups "PPIG Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ppig-discuss...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/ppig-discuss/39b5246e-8293-472d-9865-187d81f61e88n%40googlegroups.com.

Finkbine, Ronald B.

unread,
Feb 13, 2022, 8:25:31 PM2/13/22
to Peter Hornsby, Paola Kathuria, PPIG Discuss
I believe that Literate Programming was an attempt to solve this problem. Put the docs in with the code and when the code changes, just maybe the programmer will change the docs since they are together in the same file.


It is one of those projects that sidetracked Donald Knuth.

Ronald Finkbine, Ph.D.
Associate Professor of Computer Science
Coordinator of Lower Level CSCI
Indiana University Southeast
 



________________________________________
Sent: Friday, February 11, 2022 2:42 PM
To: Paola Kathuria
Cc: PPIG Discuss
Subject: [External] Re: [ppig-discuss] Trying to make sense of your old code

This message was sent from a non-IU address. Please exercise caution when clicking links or opening attachments from external sources.

I think the phrase is "Document your code as if the next person to maintain it is a violent sociopath who knows where you live"!

I'm not aware of research into how, but the effort put into teaching devs to document their code (and the documentation generators etc. that support this) suggest the problem is widely acknowledged.

P

On Fri, 11 Feb 2022 at 19:37, Paola Kathuria <paola...@gmail.com<mailto:paola...@gmail.com>> wrote:
I'm curious if there is research on how developers manage to navigate through their old software when they need to make changes to fix bugs.

I'm finding it really heard to remember and understand the 19K of code I wrote nearly four years ago.

It's made me realise how challenging it must be to change and maintain someone else's software, if someone leaves a team, for example.

I developed an online service for me and friends called Tell Me When (TMW) where you tell it what your interests are (genre, actors, directors, specific series) and it lets you know when anything matching turns up in the TV schedule (UK).

I developed it in Drupal 7 with a custom module in PHP (28 files. I have 3 perl and shell scripts.

I get TV schedule data by using APIs from other web sites or scraping the schedule data from web pages (downloading web pages, parsing and extracting structured data).

Over the years, the three sites twice disappear or change their web pages, breaking TMW. I have to then get deep into the code and try to understand the import and parsing software I wrote, which is fairly complex. I honestly feel as if I am stumbling around in semi-darkness.

Yes, meaningful function names, variable names and comments help, but I don't really have a sense any more of how it all hangs together. I am concerned that I my changes are making things more complex as a result.

I am not really sure what I am asking, but I wondered if anyone else recognises what I am talking about and how they manage.

Finally, if you've read this far and would like to see/use TMW (it's free), let me know and I'll send you more information.


Paola

--
You received this message because you are subscribed to the Google Groups "PPIG Discuss" group.

--
You received this message because you are subscribed to the Google Groups "PPIG Discuss" group.

Raoul Duke

unread,
Feb 14, 2022, 12:24:55 AM2/14/22
to PPIG Discuss
my unbidden $0.02

i for one do feel there are times and places for things akin to literate style cf. jupyter style notebooks. 

tho personally i think the least unlikely way to have actually successful & maintainable code would be to have truly good "executable specifications" systems. i've never had the dis/pleasure of trying any, only reading about them. e.g.

Reply all
Reply to author
Forward
0 new messages