Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

On navigating a large codebase

blog.royalsloth.eu

Post reply on HN
Print view View original

81–90 of 139 posts

Re: On navigating a large codebase

#81

Post by wwwigham »

The article mentions the importance of comments and documentation inline in code. I tend to agree - well-written code is great and all, but a good comment can bring in context external to the code and make _why_ code is what it is more clear to future readers. And reviewers. Comments explaining _what_ code does largely aren't needed - that's evident from usage. But the _why_? Some people would say code which can't be explained by one liner comments is "too clever". Well, I'm inclined to disagree - it's hard to fit a full historical justification for an awkward handling of an edge case into a single line. I once wrote a 17 line long comment above an 8 line diff; that much context felt justified to explain the odd code. A reviewer, hilariously, had this to say:

    This right here is "here be dragons" commenting level Double Dragon.
When I come back to code I've written long in the future, I think I'll be happier to have written the detailed "commenting level Double Dragon" long comments, over the more ambiguous yet still traditional `// HERE BE DRAGONS`. Mostly because that comment will give me the context I need to know if any of that _why_ has changed and thus in what way it's likely safe to change the commented code.

Re: On navigating a large codebase

#82

Post by gigatexal »

wwwigham wrote: post #81

The article mentions the importance of comments and documentation inline in code. I tend to agree - well-written code is great and all, but a good comment can bring in context external to the code and make _why_ code is what it is more clear to future readers. And reviewers. Comments explaining _what_ code does largely aren't needed - that's evident from usage. But the _why_? Some people would say code which can't be…

Please, please comment code. Junior devs like myself will thank you senior devs for throwing us a bone.

Re: On navigating a large codebase

#83

Post by mejutoco »

sillysaurusx wrote: post #45
Gehinnn wrote: post #41

Earlier quoted context omitted.

If you read/scan 10 lines a second, you still need over 24 hours non-stop to read a 1M+ code base. I doubt a random file ordering is helpful! Especially if you lose code navigation features like "go to definition".

You'd be surprised. Suppose I want to "go to definition" for a class named Saver. /^class Saver\> 19 times out of 20, this works. It's also instant; my vim will likely get me there faster than your IDE's go to definition functionality. (Looking at you, pycharm!) Here's my flow. >>> import tensorflow as tf >>> tf.train.Saver >>> from tensorflow.python.training import saver >>> saver Then I open /usr/local/lib/python3.…

Nothing wrong with this (big fan of vim myself). I can see the appeal and simplicity.

I just want to add that in Intellij you can do Ctrl + Shift + R "Saver" and it will search in all files (as dumb text matches, not usages), plus optional checks on extensions, etc. This is pretty fast too, and quite convenient, since it has a preview for each file. Not saying it is better, but it is an alternative.

Re: On navigating a large codebase

#84

Post by Erlich_Bachman »

cornel_io wrote: post #77
davidhyde wrote: post #23

This is a great article, I can relate. I specialise in replacing large parts of codebases with code that does the same thing from a business point of view but that makes future changes cheaper to make. One thing I thing that is worth mentioning is the political aspect of this sort of work. The people in power need to be comfortable with the fact that you will be introducing risk without immediate reward. That is a to…

Yes, absolutely never criticize - as a manager, the #1 thing that makes me start to hate a report is when they complain about other people's work. Most of the time they don't understand why code was written the way it was (Chesterton's fence), and even when they do and are making valid complaints it's just a dick move that doesn't help. Trust me, the lead and manager both know when someone sucks, they don't need to h…

> Trust me, the lead and manager both know when someone sucks

Through which mechanism do you think they know it? If nobody ever tells them that some piece of code is bad, this mechanism doesn't do its job.

Re: On navigating a large codebase

#85

Post by sillysaurusx »

mejutoco wrote: post #83
sillysaurusx wrote: post #45

Earlier quoted context omitted.

You'd be surprised. Suppose I want to "go to definition" for a class named Saver. /^class Saver\> 19 times out of 20, this works. It's also instant; my vim will likely get me there faster than your IDE's go to definition functionality. (Looking at you, pycharm!) Here's my flow. >>> import tensorflow as tf >>> tf.train.Saver >>> from tensorflow.python.training import saver >>> saver Then I open /usr/local/lib/python3.…

Nothing wrong with this (big fan of vim myself). I can see the appeal and simplicity. I just want to add that in Intellij you can do Ctrl + Shift + R "Saver" and it will search in all files (as dumb text matches, not usages), plus optional checks on extensions, etc. This is pretty fast too, and quite convenient, since it has a preview for each file. Not saying it is better, but it is an alternative.

I'm happy you mentioned that, because this highlights a very important difference: Your IDE would show you all "Saver" files in some checkout of Tensorflow, right? But you usually don't want to see the latest version of Tensorflow. You want to see the current version that's installed, which is somewhere under /usr/lib.

I haven't found any IDE that can easily and effortlessly do that.

Re: On navigating a large codebase

#86

Post by sydd »

disgruntledphd2 wrote: post #74
Aeolun wrote: post #68

Earlier quoted context omitted.

> good code is self-documenting I still believe this to be more or less true. The important part there is that you have to write good code though.

So, the advice is bad, as most people (including myself, no doubt), will write mediocre code, just by the shape of the distribution (assuming it's normally distributed, which is a strong assumption, but without data it's probably reasonable). Advice that relies on people caring about their craft/having the skills to do the work well doesn't scale, so it's bad advice where those things aren't true.

Also in lots of cases you are in a hurry to meet that deadline that compromises code quality. Better to leave a comment in this case than nothing

Re: On navigating a large codebase

#87

Post by tluyben2 »

TameAntelope wrote: post #40
tluyben2 wrote: post #28

Earlier quoted context omitted.

For very large codebases, this is often not an option. I know of very large 'let's write Cobol mainframe to Java' projects, burning 10s of millions of euros, that were just thrown away because they could not actually get it working in the end. And this is not limited to mainframe projects; it happens with (large) more recent projects (Java/C# mostly) as well.

For sure, it's not an option for these existing systems. But when building a new system, design it and plan for it to be retired when certain criteria are met (e.g. when it hits 100 reqs/sec, 3 years from first release, when LOC hits 100k).

Absolutely: I was only commenting on a blind 'just rewrite it' as that will always be the first reaction of tech people and quite often it is simply not feasible. But agreed, by design it can work.

Re: On navigating a large codebase

#88

Post by penguin_booze »

I'm of the opinion that use of IDE and non-essential tooling must stay in the private realm, much like one's idea of the almighty, and politics.

"This project doesn't build/can't run from command line! What the...".

"Oh well, I use my [favorite IDE]. It works for me".

"The call paths aren't intuitive!"

"My [favorite IDE] shows cool/advanced visualization. Maybe you should try it, too".

Re: On navigating a large codebase

#89

Post by hackeredje »

This was a nice read and is recognizable, probably a large part of Dilbert comics could fit in here...

There are projects that last for multiple years with larger TEAMS with the only job to entangle existing complex landscapes. Most of them fail.

Since these teams do consist of pretty smart people... I think one of the funny things you could do is list the things these people say when they start this adventure on day 1 "ah yes lets just grep stuff" or "i will start examining tests" and "i will make a spreadsheet of all interfaces" and "i will do interviews with older developers". About 6 months later the spreadsheet has become a separate application that is so complex that it is a complexity project on its own. The amount of documentation found is now about a couple of million separate documents and realization drops in that the lifetime of the universe is probably nearer as end date. The datamodels found for the gazillion databases now covers a library in itself. the end date of the universe is closer by than the end date of the project trying to understand what the environment is. And no it does not help that any developer or business person ever involved long left the company.

Comments: yes i agree. 80% is logical does not need a comment. 20% are the pieces of code coming out of meetings that lasted hours and which ended with strange outcomes that no-one will ever understand without understanding why things were setup in the way they were setup. And then there is the 20% added by junior developers who had no clue but just changed stuff here and there. It is hard to make that distinction because from the outside they look alike. Anyone trying to change the code to make it "logical" will remove the 20% illogical code and produce something maybe even working but no longer in line with desired results, also a junior mistake.

Re: On navigating a large codebase

#90

Post by hackeredje »

davidhyde wrote: post #23

This is a great article, I can relate. I specialise in replacing large parts of codebases with code that does the same thing from a business point of view but that makes future changes cheaper to make. One thing I thing that is worth mentioning is the political aspect of this sort of work. The people in power need to be comfortable with the fact that you will be introducing risk without immediate reward. That is a to…

Given time, every developer will end up in some company, doing projects, having to go trough other vast requirements, documentation, databases, interfaces and codebases to understand these.

So I think you refer to persons who do not do projects but who stay i one company for a large time versus people who do projects (and are sometimes called consultants) and in general how they communicate with each other.

Post reply on HN