project-topaz/topaz

A proposal regarding source notes for future use

TeoTwawki opened this issue · 9 comments

TeoTwawki commented

I have:

  • searched existing issues (http://project-topaz.com/issues/) to see if the issue has already been opened
  • checked the commit log to see if the issue has been resolved since my server was last updated

Additional Information (Steps to reproduce/Expected behavior) :
Often times we will find ancient notes regarding things that couldn't implemented in full intended to help future contributors and developers. The only issue with this is that it is also often not cleaned up after the thing is implemented. I propose requiring a new issue each time one of these is added to the source, with the issue number in the comment. This will make the comment easily searchable when fixing the issue. Visual Studio has a feature where you can find #TODO comments. so we could do:

//#TODO should happen after y but z needs refactored before that can happen. See issue #12345

We could then grep for the issue in the source or windows folks can use visual studio's TODO tracking. And anybody can grep the todo's and see all of them that we have marked so far. Todo's can even be their own labeled issue type here on github which may even help some folks looking for particular things that need done.

Kreidos commented

I see the logic in this idea, but another part of me sees this as a lot of unnecessary paperwork; TODO: is recognized by basically every IDE and it's easy to get the list of TODOs. As long as the comment accompanying the TODO: is descriptive enough. 🤷

TeoTwawki commented

@Kreidos right now we have many comments that do not as all include the keyword TODO though Kreidos..I am trying to encourage its use here.
image

Note it does not say TODO at all.

TeoTwawki commented

And Joe random contributor rarely knows this stuff.

Kreidos commented

Whaaaa? Who wouldn't use TODO, those maniacs. Well in these cases, that's definitely an issue. 😅

  • 👍1
TeoTwawki commented

image

  • 🚀1
zach2good commented

It's very much busywork, but could we hunt down all of these lone "false TODOs" by searching for "needs", "future", "later", "right now" etc.

And then mark them as actual TODO's?

TeoTwawki commented

Maybe. Worth a shot. I’d still like to start requiring ppl to use actual Todo and or make an issue for the thing they were missing to prevent future piles of long forgotten invalid comments. I mean I think we wanted ppl to make issues for the stuff they could not do in the prs anyway right? But I think even just having todo is fine as long as its a real todo that gets removed later when its done.

MarianArlt commented

This sounds like it should definitely be added to the style guide as a general rule if you want to push it. (Which you both confirmed)