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

The Code Is the To-Do List

executeprogram.com

Post reply on HN
Print view View original

71–80 of 80 posts

Re: The Code Is the To-Do List

#71

Post by marcosdumay »

Groxx wrote: post #25
shikoba wrote: post #23

Earlier quoted context omitted.

> Every TODO needed a date A todo is a todo. I don't see why a date is necessary.

It was just to ensure it wasn't forgotten. If it's "long term", stick it for a year out or something, it's fine. Truly timeless? Year 2999 works pretty well, or just don't use "todo" because it apparently isn't gonna happen. We fairly often used it for stuff like "X should be upgraded to fix Y by now, see if this hack is still necessary". If was not, just push it out and check again then. Or do whatever else might be…

If your TODO is forgotten, it's overwhelming likely that it wasn't very important.

You annotate the code to save some context for the next time you read it. A TODO is basically an anchor so you know where to come back as soon as you finish that requisite you are doing now. If you get anxious about deleting them, you may need to rethink your process, because it's not a suitable place for the kind of information you get anxious about losing.

Re: The Code Is the To-Do List

#72

Post by Griffinsauce »

jandrewrogers wrote: post #64
planede wrote: post #55

Earlier quoted context omitted.

I don't get why so many people likes this. No, I don't want a suddenly failing pipeline on master because of an expiring TODO. A better approach is for a TODO to be required to reference a ticket, and add a ticket. Prioritization should happen in your issue tracking, not in the code.

Many TODOs (the majority in code bases I've worked on that had them) do not require any action, they are annotations to the code base about future potential development or research. Addressing the TODO, either by removal or implementation, could be deferred indefinitely with no consequences and often are. These aren't things that need to be fixed per se. For example, I've seen TODOs widely used to document optimizati…

Those can just be added without "TODO" then? You're explicitly saying that you're marking things you are not likely to do as to-do, that seems like a bad idea whatever your preference wrt automation is.

Re: The Code Is the To-Do List

#73

Post by KronisLV »

ParetoOptimal wrote: post #60
KronisLV wrote: post #43

Earlier quoted context omitted.

> But it never does, there's always some critical new feature sales wants, or something bigger on fire. Then clearly it is not deserving of your attention according to the powers that be. If it is, then talk in the language that these parties understand better/prefer: bump up the priority of the task, add a "blocked by" or "has to be done after" link to these other issues in the tracker and tell the rest of the teamm…

> If more pushback is necessary, then do it doing any estimates (provided that you have any): "Task $FOO will take X% more time due to $BAR not being finished and slowing down development. Consider doing $BAR first and $FOO should become less complex then." Creating those estimates alone is more than the sum of total work usually. Then the problem of convincing others is itself typically more than the sum of total wo…

> Creating those estimates alone is more than the sum of total work usually.

Then simply add those hours spent estimating things to whatever time management solution that you use personally (for insights into where your time goes each quarter/year) or that your company mandates (for basically the same thing). If it's an actual problem, then simply raise it as such later down the road and look for ways to streamline things.

Most of the time you shouldn't care about how much time something takes (exceptions exist, based on the industry/project, but many deadlines are made up anyways), merely that the time to be spent on the task has been approved and that you're not doing something that isn't documented/categorized, e.g. time that "disappears" by being spent on things that don't have any sort of visibility/basis for taking up your time.

If changing how a button works takes 2 hours but writing tests takes 4 and refactoring old code takes another hour, then let the record show exactly that. If unclear requirements cause you to spend another hour or two in meetings and talking to people who didn't document code or explain their changes in merge/pull requests, then let the record show that, too.

Of course, this might vary on a per-company/project/culture basis.

> Then the problem of convincing others is itself typically more than the sum of total work.

If others in the team don't want to fix these things, then they probably aren't as important/annoying as you think they are and therefore probably won't be prioritized so highly anyways. When there are really annoying/brittle API integrations, for example, most devs usually should back you up in your efforts in making things less horrible.

> Usually metrics aren't accurate enough to be able to prove these things anyway in my experience.

You don't actually need metrics that are completely accurate, because finding ones that are is seldom easy to do or even possible, or simply not worth the effort. Having something to the tune of "This API integration can be improved, the last 3 feature requests related to it exceeded their estimates by quite a bit" should be enough, provided that you can get the other people on board.

If you cannot, then it's probably an issue of the actual work environment/culture and/or soft skills.

Re: The Code Is the To-Do List

#74

Post by everybodyknows »

Griffinsauce wrote: post #72
jandrewrogers wrote: post #64

Earlier quoted context omitted.

Many TODOs (the majority in code bases I've worked on that had them) do not require any action, they are annotations to the code base about future potential development or research. Addressing the TODO, either by removal or implementation, could be deferred indefinitely with no consequences and often are. These aren't things that need to be fixed per se. For example, I've seen TODOs widely used to document optimizati…

Those can just be added without "TODO" then? You're explicitly saying that you're marking things you are not likely to do as to-do, that seems like a bad idea whatever your preference wrt automation is.

The point is to concisely distinguish proposed action by maintainers, at whatever level of urgency, from purely descriptive comments intended for the benefit of users.

Re: The Code Is the To-Do List

#75

Post by Groxx »

ParetoOptimal wrote: post #60
KronisLV wrote: post #43

Earlier quoted context omitted.

> But it never does, there's always some critical new feature sales wants, or something bigger on fire. Then clearly it is not deserving of your attention according to the powers that be. If it is, then talk in the language that these parties understand better/prefer: bump up the priority of the task, add a "blocked by" or "has to be done after" link to these other issues in the tracker and tell the rest of the teamm…

> If more pushback is necessary, then do it doing any estimates (provided that you have any): "Task $FOO will take X% more time due to $BAR not being finished and slowing down development. Consider doing $BAR first and $FOO should become less complex then." Creating those estimates alone is more than the sum of total work usually. Then the problem of convincing others is itself typically more than the sum of total wo…

yeah, it takes more time in jira to create a task with a deadline and get it in a sprint and make sure it has an owner and find it in the backlog and move it through the workflow's steps than "is unused? delete". heck, sometimes the task takes less time than loading jira's website.

task systems are frequently awful at team-owned (not necessarily an individual) lightweight checks.

Re: The Code Is the To-Do List

#76

Post by Groxx »

KronisLV wrote: post #73
ParetoOptimal wrote: post #60

Earlier quoted context omitted.

> If more pushback is necessary, then do it doing any estimates (provided that you have any): "Task $FOO will take X% more time due to $BAR not being finished and slowing down development. Consider doing $BAR first and $FOO should become less complex then." Creating those estimates alone is more than the sum of total work usually. Then the problem of convincing others is itself typically more than the sum of total wo…

> Creating those estimates alone is more than the sum of total work usually. Then simply add those hours spent estimating things to whatever time management solution that you use personally (for insights into where your time goes each quarter/year) or that your company mandates (for basically the same thing). If it's an actual problem, then simply raise it as such later down the road and look for ways to streamline t…

>Then simply add those hours spent estimating things to whatever time management solution that you use personally (for insights into where your time goes each quarter/year) or that your company mandates (for basically the same thing).

Which sometimes means it doesn't happen because it's not valuable enough at any given instant to go through that multi-hour process, yes.

Lightweight tasks exist. As much as I generally agree with you, following your rules means you either do not ever do them, or you bloat them to multiple times larger than necessary. And correcting a company's task-management process as a whole is not always feasible either.

Re: The Code Is the To-Do List

#77

Post by Groxx »

marcosdumay wrote: post #71
Groxx wrote: post #25

Earlier quoted context omitted.

It was just to ensure it wasn't forgotten. If it's "long term", stick it for a year out or something, it's fine. Truly timeless? Year 2999 works pretty well, or just don't use "todo" because it apparently isn't gonna happen. We fairly often used it for stuff like "X should be upgraded to fix Y by now, see if this hack is still necessary". If was not, just push it out and check again then. Or do whatever else might be…

If your TODO is forgotten, it's overwhelming likely that it wasn't very important. You annotate the code to save some context for the next time you read it. A TODO is basically an anchor so you know where to come back as soon as you finish that requisite you are doing now. If you get anxious about deleting them, you may need to rethink your process, because it's not a suitable place for the kind of information you ge…

>If your TODO is forgotten, it's overwhelming likely that it wasn't very important.

Sometimes, but not always. We deleted the ones that were not, and finished the ones that were.

As far as noticing these by hand: my current project is about 600,000 lines of hand-written code, not including several libraries we also author and use in it, nor other projects I'm also heavily involved in. I haven't even looked at all the code yet, much less do so on any regular cadence. Forgetting is something you plan on and address up-front, not something you just let happen.

Re: The Code Is the To-Do List

#78

Post by Groxx »

quickthrower2 wrote: post #46
edvald wrote: post #42

One trick I employ for myself is: throw "TODO" // Substitute for your language's syntax of course. I find this especially handy when writing test specs, but it's also handy when creating new functions etc. For tests I lay out the test descriptions with just this one line in the function body. For new functions/methods I can define the function and its return type (assuming a type-safe language) which makes the code u…

That sounds good within a feature branch but you wouldn’t merge those to main, right?

to be fair, that is what the linked post is talking about :) so super-explicitly breaking things serves pretty much the same purpose, as long as you have attentive reviewers and/or tests that touch that code.

Re: The Code Is the To-Do List

#79

Post by adamddev1 »

tw102 wrote: post #30
adamddev1 wrote: post #10

This is a great idea. But I would like my eslint to produce a WARNING, not an ERROR when I have a certain keyword in a comment. Like if I wrote FIXME in a comment I would like it to produce and eslint warning which would let the code compile and reload (in create-react-app let's say) but it wouldn't build in CI because it has a warning. Is there a way to do this with eslint?

This is exactly what the article describes. Lint ERRORs that block CI but not compilation.

No unfortunately for me using create-react-app an ERROR like this article's config produces blocks compilation as well. I would need it to output a WARNING for compilation to continue but I can't see how to do that with no-warning-comments

Re: The Code Is the To-Do List

#80

Post by KronisLV »

Groxx wrote: post #76
KronisLV wrote: post #73

Earlier quoted context omitted.

> Creating those estimates alone is more than the sum of total work usually. Then simply add those hours spent estimating things to whatever time management solution that you use personally (for insights into where your time goes each quarter/year) or that your company mandates (for basically the same thing). If it's an actual problem, then simply raise it as such later down the road and look for ways to streamline t…

> Then simply add those hours spent estimating things to whatever time management solution that you use personally (for insights into where your time goes each quarter/year) or that your company mandates (for basically the same thing). Which sometimes means it doesn't happen because it's not valuable enough at any given instant to go through that multi-hour process, yes. Lightweight tasks exist. As much as I generall…

> Lightweight tasks exist. As much as I generally agree with you, following your rules means you either do not ever do them, or you bloat them to multiple times larger than necessary. And correcting a company's task-management process as a whole is not always feasible either.

Creating a short Jira issue and poking someone about including it in the current sprint should take about 10 minutes in total, if you want a decent description and are okay with occasionally not focusing on the "ceremonies" of sprint grooming too much, since as you say, some tasks are indeed small (and as long as this doesn't lead to scope creep, e.g. fixes/refactoring instead of new features this way).

Of course, that may always not be viable and i see where you're coming from - yours is also a valid stance to take and i see why focusing on an issue tracker too much would be cumbersome. Then again, in my eyes that's a bit like the difference between having almost entirely empty pull/merge requests and having a description of why the changes exist, a summary of what's done (high level overview), additional relevant details and images/GIFs of the changes in action, DB schema diagrams or anything of the sort.

I feel like additional information will always be useful, as long as it doesn't get in the way of getting things done (for an analogy, think along the lines of covering most of the business logic with tests vs doing TDD against a bloated web framework and thus not getting anything done - a few tradeoffs to be made).

Post reply on HN