1

Sometimes there are elaborate discussions about a subject, and while finally developing the program, you want to refer to a mail ... but then people still continue mailing about the subject, so the mail chain continues.

How do you refer to a particular mail in the comment of the source code?

There are two obvious ways:

  1. Something like Ref. mail from [email protected], title "Something very long" on February 30 1970 at 13:12 PM :-)
  2. Use the message-ID of the mail (I've found one like AM9P194MB94111DCB13CB9FAEC6F0Q488F6BD9@AM9J594MB1411.EUR164.PROD.OUTLOOK.COM)

The first way is very human readable, but might cause doubt.
The second way is very clear, but useless (I tried to use the message-ID to find a mail in my MS-Outlook inbox, and that didn't work).

Does anybody know a correct and humanly usable way to refer to an e-mail in source code comments? Or is the answer "This question is the exact reason why never to use e-mail references in source code comments."?

Improve this question

5 Answers 5

Reset to default
6

I would recommend creating an issue in a defect tracking tool like Jira and referring to the Jira issue rather than the originating email in your code comments. This will pick up any work that has been done to resolve/ignore the issue plus possibly multiple opinions from developers.

Improve this answer
3
  • Better than refering to an email message, but those tools too can disappear, especially if the project lives for a long time. E.g. where I'm working now we transitioned to Jira about 5 years ago from another bugtracker and there are still references to that one in the code that nobody can look up. And next year we're going to move away from Jira because someone in finance decided that the license is too expensive, so we'll lose that as well (and probably have to resort to keeping track of issues using a spreadsheet). Commented Oct 20, 2021 at 8:44
  • @jwenting You raise a very valid point. Unfortunately the only way to fix this is to copy all the relevant information into code comments and this has its own problems. Commented Oct 20, 2021 at 8:50
  • ikr. There is no perfect solution. Best you can do is mitigation. If a replacement bug tracker can import the old one for example that's a massive plus already Commented Oct 20, 2021 at 8:53
4

Bad idea overall. Email is ephemeral. People not in the recipient list would have no idea what is being referred to, and in time the mail archives are gone from servers and peoples' computers, losing all information.

If it's relevant enough to need to be referenced, place the information somewhere where it's reasonably sure to be retained for the lifetime of the project. A wiki, website, document in the project directory, whatever works for your team.

Improve this answer
1

Or is the answer "This question is the exact reason why never to use e-mail references in source code comments."?

This question is the exact reason why … this discussion should have been taking place on the appropriate forum to begin with, where (depending on your organization), the "appropriate forum" might be

  • A ticket in a Project Management system such as Jira, Bugzilla, GitHub Issues, …,
  • A Wiki,
  • A Discussion Forum with a publicly accessible (at least to anyone who can also access the code) web archive,
  • A properly set up Mailing List with a publicly accessible (at least to anyone who can also access the code) web archive. I am referring to a mailing list ran by a mailing list manager such as Majordomo, not a private email with multiple people in the To: line.

So, in other words, you can use email, but make sure to use it properly. Examples of a non-trivial project ran exclusively using email for project management is the Linux Kernel. (Nowadays, there are also various bug trackers for subproject and there is a bug tracker for the whole kernel, but email still is the current main tool and has historically been the only tool for a very long time.)

A slightly less well-known example is the development of the YARV Ruby execution engine and the Ruby programming language, which use an English language mailing list, a Japanese language mailing list, and a Project Management tool. The tool and the mailing lists are interconnected, where opening an issue automatically generates an email to the mailing list and automatically inserts a link to the email thread in the archives into the ticket.

Improve this answer
2
  • it's quite likely the discussion started with a simple question like "is this what should happen?" and blew up from there, the ticket being created only later. Yes, the email exchange should be included in the ticket, but it's quite normal for the ticket to come after the email exchange (usually as a result of the email exchange). Commented Oct 20, 2021 at 8:45
  • Actually, even if the email was the wrong channel, you're right in pointing out that, hopefully, a ticket tracker is used... And in that case, they might as well just add the email as a comment or an attachment of the ticket and reference the ticket. Simple enough. It's not necessarily as future-proof as having the reference material local to the codebase, though, but good enough for many cases. Commented Oct 21, 2021 at 0:25
1

There could be other alternatives, which I'll just mention for the sake of completion, although I don't see myself using these...

Export the Email to a File in Your Repository

Export the email to a file in a specific folder of your repository, named after the message ID, and reference the path to the file.

(Of course, then comes the question of the export format to use...)

Export the Email in Base64 and Add to the Comment :)

A bit tongue in cheek, but you have to agree it's nice in that:

  • it's text-based,
  • it's local to your comment, where you need it,
  • there's no ambiguity.

Of course, not so practical. But you can't have it all.

Beware of Privacy Issues

By using one of these 2 approaches, you may be sharing people's thoughts and content with other parties with whom they did not agree for you to share it.

Improve this answer
0

my previous company used to do this and they create specific page or board just for this attachment that contains sensitive information only for permanent employee. Personally, I would just screenshot necessary information and blur everything else to make it simple, put it on confluence or jira ticket and refer it on your source code..

Improve this answer

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.