Ask HN: How should I proceed at work?

[pietrrrek]

I started working (part time as a student) at this small [1] company back in April when the virus just hit which lead to a rocky introduction to the systems that are in place. The other developer is going into retirement in about two months and, thus far, the company has had trouble finding an appropriate replacement.

The system is a large website built with AngularJS and SailsJS. The codebase is very large (at least in my unexperienced eyes) which would not be an issue had it been properly documented, most components do not have a single comment in them (except for code which has been commented out) and also lack any external documentation. To add on to the mess, the code style is also not very reader friendly (cryptic variable names, unnamed constants etc.).

I see the fact that the above mentioned employee is going into retirement as an opportunity to "do things right" and start over by rewriting/porting the website, writing proper documentation along the way, and upgrading certain technologies (e.g. JS -> TS and SVN -> Git) but I feel that I'm in way over my head. I'm about to finish my Bachelors this summer and plan on starting on a Masters immediately.

I feel competent enough in writing software but not in creating a feasible architecture for such a large project, so my question is; how should I proceed? I think that the changes that I've come up with would be a net positive for the company and would make the life of future developers at the company easier (that is if the implementation is good enough). Could you point me to any ressources that might be of help in my situation?

[1] There are no more than 4 IT employees where only I and another one are developers

[mimixco]

Big changes in architecture are often catastrophic and result in far more debugging costs than just fixing the current product piecemeal. I know that sounds terrible and unfun, but read Fowler on the concepts of refactoring and you'll see that Job #1 is maintaining a working product. In other words, don't throw the baby out. Change the bath water.

In refactoring, you attack one piece of "code smell" at a time. You can improve one variable name at a time, for example, and test to make sure it works. You can refactor a function and not touch any of its dependencies and see if it still works.

The worst thing would be to start a big rewrite and then leave the company without anyone to fix the old thing or complete the new one. I totally agree with you that documenting the current monster is a must-do. As you write that doc, you'll see where the biggest code smells are. Things that make no sense in the doc or are hard to relate together in writing are probably poorly designed code.

On the subject of comments, I think they're overrated. Comments are only necessary when the code isn't self-documenting, which implies that it has a poor naming strategy or uses patterns that are difficult to recognize visually. It's better to fix the code (especially names of variables and functions) to make the code itself human readable than it is to write comments.

Hope that helps!

[jacobobryant]

It's hard to say for sure without having first-hand experience with the code base. But rewriting messy projects from scratch is often a pitfall, and I would be very cautious about taking that route (especially given "I feel that I'm in way over my head" and "I feel competent enough in ... but not in creating a feasible architecture"). The last thing you want is to spend months creating a new project that ends up being not much better than what you started with, a scenario that happens all too frequently.

I would consider using this as an opportunity to learn and refactor a large code base. That's an extremely valuable skill, and it's hard to get it without situations like these (whereas anyone can get practice creating a new project on the weekend). You might have to spend a lot of time staring at the code, feeling like you're not making much progress, but it'll (hopefully) be worth it.

On the other hand, it is possible that the code base is just horrible and should be nuked, so use your own judgment :).

[uberman]

Please don't port the system or switch to a new source control system. I completely understand the temptation, but these are your best guess at priorities and almost certainly not your company's priorities.

Additionally if you switch to SVN to git you will likely drop all history. history that might be tied to an issue tracking system, even if that is an informal one.

In my opinion, your best first move will be to document the code as you work through it.

[llampx]

A new engineer who wants to throw away everything and start from scratch. I've never heard that one before.

[pietrrrek]

This stereotype is the reason why I wrote this post, i.e. to avoid starting a rewrite only based on my own, very limited, experience.

Seeing the contents of sister comments, I see that a full rewrite is likely a _very_ bad idea.

[tsjq]

you suggesting the retiring employee be re-hired to fix this code ?

[sloaken]

First off, sorry for your pain, and if you stay it will be a rough ride.

Initially I would say make sure you are paid for overtime, as when this thing breaks they will expect you to stay until it is done.

Other option is to get your resume together and plan for a new job.

Second make sure YOU have a backup copy of the code. Yeah yeah they make backups... no you need a separate one. Okay maybe you will not, but the smart money is saying you will. Let us just hope you never need your personal backup. Do it now, when you find out you needed it, it is too late.

Third make sure your boss realizes what a S** sandwich this is that you are being left with. The 'other' developer is clearly not a professional. Your boss needs to realize that this other guy has left you with a HUGE technical debt. If your boss actually needs this software, then he is going to have to spend a ton of resources fixing it.

Next start documenting what is there. Sit the guy down and start having them explain the 1) Requirements including the goes into and goes out of. Be leery of the would be nice if it does this. 2) Now start going over the design. What are the 2/3 or 4 MAJOR components. What does each do. How do you build / compose them. How do you test them. Make sure all of this is written. Test what you have written. 3) Understand the entry point of each system, and how to debug it. 4) for each major system ... what are the 2/3/ or 4 major components. What does each ... <yes recursive>

Although I agree you are over your head, it is also a great opportunity, if they pay overtime and respect the herculean effort they are asking you. Sadly most places I have worked at did not understand how bad it is.

Rewrite would take a LOT of effort. As it stands you can blame the previous person and their management for everything that goes wrong. Once you rewrite you own it.

While rewriting you have to have the old stuff running. If you break it down into parts, you can slowly replace a part at a time. Same architecture, just better coding.

I wish you the best of luck. I have been in similar shoes all too often.

First time, after documenting the code enough to make it understandable, started the rewrite. Person I replaced was around for 3 months.

Second time, redid just the variable names, no variable name was less than 50 character, variable names included project name and company. Other person was around, he resented my changing the variable names.

Third time, was laidoffed after 9 months as the project had not progressed enough. Entire team doing the development left a month before I arrived. They only had pretty pictures.

Fourth time, I started a week before the developer left. He had his working project and a 'new and improved' that was almost done. The week of overlap was spent with him showing me things. I was busy trying to absorb what he was saying, and did not realize he had not documented a thing. Documented his stuff as best I could and kept the ship afloat, until I could get someone else to create a replacement.