www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Source changes should include date of change

reply Josphe Brigmo <JospheBrigmo gmail.com> writes:
Having source code that doesn't show changes with dates is pretty 
useless for diagnostics. I realize that git has the changes but 
the source code should.

If some code is added or changed it is very simple to add the 
date of change in a comment.

// Date: Date1, Date2, Date3, ....

Anything below a was changed at those dates.



Why not also add a link to the git hub patch or bugzilla or 
whatever?
Sep 07 2018
next sibling parent reply Colin <grogan.colin gmail.com> writes:
On Saturday, 8 September 2018 at 06:59:28 UTC, Josphe Brigmo 
wrote:
 Having source code that doesn't show changes with dates is 
 pretty useless for diagnostics. I realize that git has the 
 changes but the source code should.

 If some code is added or changed it is very simple to add the 
 date of change in a comment.

 // Date: Date1, Date2, Date3, ....

 Anything below a was changed at those dates.



 Why not also add a link to the git hub patch or bugzilla or 
 whatever?
Git is the tool that's used to manage changes, including viewing the changes. A lot of dev time has gone into it and it works really well. Some ad hoc comment system in source code to point out changes will never be as good. Just Use Git!
Sep 08 2018
next sibling parent reply Josphe Brigmo <JospheBrigmo gmail.com> writes:
On Saturday, 8 September 2018 at 07:08:46 UTC, Colin wrote:
 On Saturday, 8 September 2018 at 06:59:28 UTC, Josphe Brigmo 
 wrote:
 Having source code that doesn't show changes with dates is 
 pretty useless for diagnostics. I realize that git has the 
 changes but the source code should.

 If some code is added or changed it is very simple to add the 
 date of change in a comment.

 // Date: Date1, Date2, Date3, ....

 Anything below a was changed at those dates.



 Why not also add a link to the git hub patch or bugzilla or 
 whatever?
Git is the tool that's used to manage changes, including viewing the changes. A lot of dev time has gone into it and it works really well. Some ad hoc comment system in source code to point out changes will never be as good. Just Use Git!
Um, I didn't say don't use Git! Your illogic is that you believe that one can have only one or the other when one can have both. Hence, you are excluding a completely valid addition. You think it is an alternative. You are wrong. Please think about the question before you answer next time so that you don't get in the habit of doing it. No one said that Git couldn't be used and telling me to use it is very arrogant of yourself. The fact of the matter is that dates in source code will help when git is not available and one only has the source code.
Sep 08 2018
next sibling parent Norm <norm.rowtree gmail.com> writes:
On Saturday, 8 September 2018 at 11:29:15 UTC, Josphe Brigmo 
wrote:
 On Saturday, 8 September 2018 at 07:08:46 UTC, Colin wrote:
 On Saturday, 8 September 2018 at 06:59:28 UTC, Josphe Brigmo 
 wrote:
 Having source code that doesn't show changes with dates is 
 pretty useless for diagnostics. I realize that git has the 
 changes but the source code should.

 If some code is added or changed it is very simple to add the 
 date of change in a comment.

 // Date: Date1, Date2, Date3, ....

 Anything below a was changed at those dates.



 Why not also add a link to the git hub patch or bugzilla or 
 whatever?
Git is the tool that's used to manage changes, including viewing the changes. A lot of dev time has gone into it and it works really well. Some ad hoc comment system in source code to point out changes will never be as good. Just Use Git!
Um, I didn't say don't use Git! Your illogic is that you believe that one can have only one or the other when one can have both. Hence, you are excluding a completely valid addition. You think it is an alternative. You are wrong. Please think about the question before you answer next time so that you don't get in the habit of doing it. No one said that Git couldn't be used and telling me to use it is very arrogant of yourself. The fact of the matter is that dates in source code will help when git is not available and one only has the source code.
Comments showing last modified date are pure noise. The code is what gets executed and what you should focus on. If you need history look at git log. The date is generally useless and code deltas are what you want and this is why VCS tools exist. The only caveat to all that is a copyright statement, which should include the year. But this is orthogonal sprinkling dates throughout your code base. But if you really want to do this more power to you, it is your code. Set up a hook in your fav. editor that inserts a date comment each time you enter ";" followed by the return key. Bye, Norm
Sep 08 2018
prev sibling next sibling parent reply tide <tide tide.tide> writes:
On Saturday, 8 September 2018 at 11:29:15 UTC, Josphe Brigmo 
wrote:
 On Saturday, 8 September 2018 at 07:08:46 UTC, Colin wrote:
 On Saturday, 8 September 2018 at 06:59:28 UTC, Josphe Brigmo 
 wrote:
 Having source code that doesn't show changes with dates is 
 pretty useless for diagnostics. I realize that git has the 
 changes but the source code should.

 If some code is added or changed it is very simple to add the 
 date of change in a comment.

 // Date: Date1, Date2, Date3, ....

 Anything below a was changed at those dates.



 Why not also add a link to the git hub patch or bugzilla or 
 whatever?
Git is the tool that's used to manage changes, including viewing the changes. A lot of dev time has gone into it and it works really well. Some ad hoc comment system in source code to point out changes will never be as good. Just Use Git!
Um, I didn't say don't use Git! Your illogic is that you believe that one can have only one or the other when one can have both. Hence, you are excluding a completely valid addition. You think it is an alternative. You are wrong. Please think about the question before you answer next time so that you don't get in the habit of doing it. No one said that Git couldn't be used and telling me to use it is very arrogant of yourself. The fact of the matter is that dates in source code will help when git is not available and one only has the source code.
Dates won't help, if you have a comment with a date that states everything under it was modified at that date. What happens when there's a split of 3-4 lines between modifications? Just how many of these comments are there going to be? This will be unusable, adds very little useful information, won't work for past changes overwritten changes and deletions. Just use git, that's what it is designed to do without polluting source code with useless comments. If you have the source code, there's no reason you won't have the git repo as well. It can all be stored and used locally on your own machine.
Sep 08 2018
parent Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Saturday, September 8, 2018 6:35:32 AM MDT tide via Digitalmars-d wrote:
 Dates won't help, if you have a comment with a date that states
 everything under it was modified at that date. What happens when
 there's a split of 3-4 lines between modifications? Just how many
 of these comments are there going to be? This will be unusable,
 adds very little useful information, won't work for past changes
 overwritten changes and deletions.

 Just use git, that's what it is designed to do without polluting
 source code with useless comments. If you have the source code,
 there's no reason you won't have the git repo as well. It can all
 be stored and used locally on your own machine.
This also hearkens back to the general issues of comments in code. Many people like to argue that the code should speak for itself and that if comments are necessary, there's a problem. I don't think that that's entirely true - comments can sometimes be vital for explaining the reasons by a piece of code - but comments not matching the code can be a very real problem. Every comment that's in the code then needs to be maintained along with the code, and that often doesn't happen. If dates start getting sprinkled throughout the code, then there's a good chance that they won't be up-to-date. And of course, as you point out, it becomes pretty problematic when the changes aren't all together in a block. Honestly, arguing for putting dates in the code, because you can't rely on looking that information up via source control is like arguing that all of the commit comments should be in the code. It really doesn't make any sense. This is an area where it really is the source control system's job to deal with it. git blame (or the equivalent tool for whatever source control system is being used) is exactly what should be used in this sort of situation. - Jonathan M Davis
Sep 08 2018
prev sibling next sibling parent reply Paul Backus <snarwin gmail.com> writes:
On Saturday, 8 September 2018 at 11:29:15 UTC, Josphe Brigmo 
wrote:
 Um, I didn't say don't use Git!

 Your illogic is that you believe that one can have only one or 
 the other when one can have both. Hence, you are excluding a 
 completely valid addition. You think it is an alternative. You 
 are wrong. Please think about the question before you answer 
 next time so that you don't get in the habit of doing it. No 
 one said that Git couldn't be used and telling me to use it is 
 very arrogant of yourself.

 The fact of the matter is that dates in source code will help 
 when git is not available and one only has the source code.
Git does a better job of tracking history automatically than anyone could ever realistically do by hand. So not only would date comments be useless duplication of work, they'd be useless duplication of inferior quality to the original. It would be like keeping a horse at your house at all times, in case your car breaks down. Even if it's occasionally useful, it is not worth the constant maintenance costs of feeding the horse, cleaning the stable, etc. If your car breaks down, you find a way to get it fixed. If git isn't available to you, you find a way to make it available.
Sep 08 2018
parent Patrick Schluter <Patrick.Schluter bbox.fr> writes:
On Saturday, 8 September 2018 at 12:36:01 UTC, Paul Backus wrote:
 On Saturday, 8 September 2018 at 11:29:15 UTC, Josphe Brigmo 
 wrote:
 Um, I didn't say don't use Git!

 Your illogic is that you believe that one can have only one or 
 the other when one can have both. Hence, you are excluding a 
 completely valid addition. You think it is an alternative. You 
 are wrong. Please think about the question before you answer 
 next time so that you don't get in the habit of doing it. No 
 one said that Git couldn't be used and telling me to use it is 
 very arrogant of yourself.

 The fact of the matter is that dates in source code will help 
 when git is not available and one only has the source code.
Git does a better job of tracking history automatically than anyone could ever realistically do by hand. So not only would date comments be useless duplication of work, they'd be useless duplication of inferior quality to the original. It would be like keeping a horse at your house at all times, in case your car breaks down. Even if it's occasionally useful, it is not worth the constant maintenance costs of feeding the horse, cleaning the stable, etc. If your car breaks down, you find a way to get it fixed. If git isn't available to you, you find a way to make it available.
Interactive programs like GitExtension show exactly the the date of each line with the git blame view. Visual Studio Code with the D extension also shows the commit info when hovering over the code. There are a lot of nice way to use the git info to get the date of the line. Dates in the comments are utterly useless. They are imo even counter productive. The information has not bearing with the actual code. There is no point in putting dates in the comments when the code is managed by git.
Sep 08 2018
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 9/8/2018 4:29 AM, Josphe Brigmo wrote:
 Um, I didn't say don't use Git!
I've done this manually before git. I can guarantee you that the dates put in the file are invariably wrong, incomplete, or non-existent. But if you bring up a source file in github, and click on the "Blame" button, it'll tell you, for every line in the source, which PR last changed that line.
Sep 08 2018
parent reply Josphe Brigmo <JospheBrigmo gmail.com> writes:
On Sunday, 9 September 2018 at 02:49:45 UTC, Walter Bright wrote:
 On 9/8/2018 4:29 AM, Josphe Brigmo wrote:
 Um, I didn't say don't use Git!
I've done this manually before git. I can guarantee you that the dates put in the file are invariably wrong, incomplete, or non-existent. But if you bring up a source file in github, and click on the "Blame" button, it'll tell you, for every line in the source, which PR last changed that line.
Yes, but if one has access to git then that is pointless. Yes, dates go out of sync and are hard to maintain. THis is why it takes a more complex system to cover those issues property. One wouldn't just include the date but other meta information that removes and reduces these problems that people complain about. If git would automatically do the dates then one could download the source code. Git would be the central repository and if one wanted an offline version that had enough info in it such as the data a change was made, who changed it, the date the file was generated etc, then it would be better than having nothing. To throw the baby out with the bath water is wrong. Special comments could be used so they could easily be removed if desired along with any necessary information such as the library version, dates the code was changed, etc. No need to include everything. Some information is better than none, that is always the case. Data(knowledge) can't hurt you, only the lack of it. The thing is, none of this shit hurts anything. Comments don't change programs so really it is just an issue about bloat and rot. The rot is covered by git hub automatically generating all the info(then it becomes no different than the problem of versioning with everything, want an update, just download it from git). The bloat is minimum and the bloat is precisely valid information(it's not like it is gibberish). So, for people to pretend that this is evil and shouldn't be done just because they feel it is not as good as using git directly is really moronic. What they are saying is "Because git hub has it all we shouldn't go the extra step to provide partial information". But the problem with such logic is git up is not always available and not everyone wants to go that route. So, instead of a compromise these people want to enforce some absolute law that they imagined they can enforce(some people murder over such things, just to show you how bad it can get). It's one thing to say that it shouldn't be done because no one thinks it's important(e.g., almost everyone uses git hub) and quite a different thing to dictate some fictitious authoritative dictator persona as if the dictator is god and knows everything. 30 years ago if asked most programmers about starting a git hub they would laugh at you and tell you it is not needed. The sad fact is that most people have no clue what is actually needed and what is good and what is bad. They just follow the asses in front of them, usually, eventually, over a cliff.
Sep 08 2018
next sibling parent reply Paul Backus <snarwin gmail.com> writes:
On Sunday, 9 September 2018 at 04:37:48 UTC, Josphe Brigmo wrote:
 If git would automatically do the dates then one could download 
 the source code. Git would be the central repository and if one 
 wanted an offline version that had enough info in it such as 
 the data a change was made, who changed it, the date the file 
 was generated etc, then it would be better than having nothing.

 [...]

 The thing is, none of this shit hurts anything. Comments don't 
 change programs so really it is just an issue about bloat and 
 rot. The rot is covered by git hub automatically generating all 
 the info(then it becomes no different than the problem of 
 versioning with everything, want an update, just download it 
 from git). The bloat is minimum and the bloat is precisely 
 valid information(it's not like it is gibberish).
I think perhaps you are laboring under a severe misunderstanding of what git is, and how git and Github actually work. Git is a version control system. It records historical snapshots ("commits") of a project, along with metadata like date and author, and lets you navigate between different versions. The collection of data and metadata saved by git for a particular project is called a "git repository". Github is a website for hosting git repositories. When you download the dmd source code from Github using `git clone`, you receive a complete copy of the entire history of dmd, including both the commits themselves and the metadata associated with them. That's why there's no need to add comments--all the data you want is already there, not just on Github, but in *every single* offline copy. When we say "just use git," we don't mean "use Github, the website," we mean "use git, the version control system, to view the historical information *in your local copy*".
Sep 08 2018
parent rikki cattermole <rikki cattermole.co.nz> writes:
On 09/09/2018 5:43 PM, Paul Backus wrote:
 On Sunday, 9 September 2018 at 04:37:48 UTC, Josphe Brigmo wrote:
 If git would automatically do the dates then one could download the 
 source code. Git would be the central repository and if one wanted an 
 offline version that had enough info in it such as the data a change 
 was made, who changed it, the date the file was generated etc, then it 
 would be better than having nothing.

 [...]

 The thing is, none of this shit hurts anything. Comments don't change 
 programs so really it is just an issue about bloat and rot. The rot is 
 covered by git hub automatically generating all the info(then it 
 becomes no different than the problem of versioning with everything, 
 want an update, just download it from git). The bloat is minimum and 
 the bloat is precisely valid information(it's not like it is gibberish).
I think perhaps you are laboring under a severe misunderstanding of what git is, and how git and Github actually work. Git is a version control system. It records historical snapshots ("commits") of a project, along with metadata like date and author, and lets you navigate between different versions. The collection of data and metadata saved by git for a particular project is called a "git repository". Github is a website for hosting git repositories. When you download the dmd source code from Github using `git clone`, you receive a complete copy of the entire history of dmd, including both the commits themselves and the metadata associated with them. That's why there's no need to add comments--all the data you want is already there, not just on Github, but in *every single* offline copy. When we say "just use git," we don't mean "use Github, the website," we mean "use git, the version control system, to view the historical information *in your local copy*".
Or Mercurial, SVN, CVS... we are not using mainframes anymore. We can afford the cost of a full blown database with all this extra information in it as well as all the past changes. Anyways, we're no longer talking hundreds of lines of code. We talk in millions of lines of code where comments just don't scale to.
Sep 08 2018
prev sibling next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 9/8/2018 9:37 PM, Josphe Brigmo wrote:
 [...]s**t[...]
We expect professional demeanor here. Please don't use such language.
Sep 08 2018
prev sibling parent Neia Neutuladh <neia ikeran.org> writes:
On Sunday, 9 September 2018 at 04:37:48 UTC, Josphe Brigmo wrote:
 If git would automatically do the dates
It does. To get changes for a whole file: git log filename To get changes for part of a file: git log -L startLine,endLine filename There are formatting options for git log to pare it down to what's useful to you.
Sep 09 2018
prev sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 8 September 2018 at 07:08:46 UTC, Colin wrote:
 Some ad hoc comment system in source code to point out changes 
 will never be as good.

 Just Use Git!
I'd agree for implementation changes, but *interface* changes should be not just in the comment, but in a doc comment. Ddoc specifically has a "History:" section for this (and adrdox also supports "Since:"). So if you add a function, say when it was added, either a release version number or the date it was released. When you change function arguments, show it too. Then if someone is looking at code and looking it up in the documentation, they can see that like it called "foo!int" and it is "History: added support for int in version 2.089, Sept 2018." and then be like "oh that's why it is erroring, my thing is version 2.088"
Sep 08 2018
prev sibling parent reply Neia Neutuladh <neia ikeran.org> writes:
On Saturday, 8 September 2018 at 06:59:28 UTC, Josphe Brigmo 
wrote:
 Having source code that doesn't show changes with dates is 
 pretty useless for diagnostics. I realize that git has the 
 changes but the source code should.
What problem did you encounter where you had trouble getting the information you needed with git blame, where a source code comment listing change dates would help?
 Why not also add a link to the git hub patch
Because that's a lot of work to replicate something git already does.
 or bugzilla or whatever?
Currently, some code in phobos does reference issues on the dlang bugzilla. The common categories for this include: * Explaining why we want things to work this way, if that requires more than a couple sentences of explanation * Pointing out what problem this is a workaround for * Pointing out which past problem motivated this unittest Things that help you understand the code as it currently is. Is there some situation you've encountered in the past where that kind of comment wasn't enough?
Sep 08 2018
parent reply Josphe Brigmo <JospheBrigmo gmail.com> writes:
On Saturday, 8 September 2018 at 18:47:39 UTC, Neia Neutuladh 
wrote:
 On Saturday, 8 September 2018 at 06:59:28 UTC, Josphe Brigmo 
 wrote:
 Having source code that doesn't show changes with dates is 
 pretty useless for diagnostics. I realize that git has the 
 changes but the source code should.
What problem did you encounter where you had trouble getting the information you needed with git blame, where a source code comment listing change dates would help?
 Why not also add a link to the git hub patch
Because that's a lot of work to replicate something git already does.
 or bugzilla or whatever?
Currently, some code in phobos does reference issues on the dlang bugzilla. The common categories for this include: * Explaining why we want things to work this way, if that requires more than a couple sentences of explanation * Pointing out what problem this is a workaround for * Pointing out which past problem motivated this unittest Things that help you understand the code as it currently is. Is there some situation you've encountered in the past where that kind of comment wasn't enough?
This has nothing to do with git. People think git is the end all be all. What if git is not available, then what? It's moronic to think that one has to use one or the other when both options are available and both only add information. The same people that are saying use git used to say that git was overkill because it wasn't needed before it became popular. They are simply always looking for a way to justify their current belief. They think the world is black or white. They then pretend that a choice has to be made between two possibilities. e.g., either religion or science(but not both because they only have xor in their operations), either black or white. Either yes or no, either hot or cold, either this or that. They then go crazy when someone offers the other choice as a solution because they feel they will lose their safety blanket. How hard would it be to automate dating for dmd source so that everything is consistent in a way that makes sense? See, people rather blow off their bad leg just so they have one good leg rather than have a bad leg and a good leg. "A false dilemma is a type of informal fallacy in which something is falsely claimed to be an "either/or" situation, when in fact there is at least one additional option. A false dilemma can arise intentionally, when a fallacy is used in an attempt to force a choice or outcome." BTW, not every uses git and git is not always available so to say "You must use git" just sounds likes arrogant(of course, arrogant people don't think they are arrogant). When I have to dive in to source code to find something, it helps to have some clue when the code was added. A clue is better than being in the dark, but as we know, some people just like to bury their head in the sand. For them, ignorance is bliss.
Sep 08 2018
next sibling parent reply Neia Neutuladh <neia ikeran.org> writes:
On Sunday, 9 September 2018 at 01:27:06 UTC, Josphe Brigmo wrote:
 How hard would it be to automate dating for dmd source so that 
 everything is consistent in a way that makes sense?
Perhaps you could find out by trying to implement such a system? That's what I usually do. You haven't described the problems you want to address in any detail, so you're the only one who knows what would make sense. That means you're the only person who could even hope to estimate the difficulty. Plus it would be a fair bit of work that nobody else seems that interested in, so unless you're offering to pay, you're the only one motivated to do the work. But perhaps, if you presented your results, they would be interesting enough for others to adopt.
Sep 08 2018
parent reply Josphe Brigmo <JospheBrigmo gmail.com> writes:
On Sunday, 9 September 2018 at 02:48:40 UTC, Neia Neutuladh wrote:
 On Sunday, 9 September 2018 at 01:27:06 UTC, Josphe Brigmo 
 wrote:
 How hard would it be to automate dating for dmd source so that 
 everything is consistent in a way that makes sense?
Perhaps you could find out by trying to implement such a system? That's what I usually do. You haven't described the problems you want to address in any detail, so you're the only one who knows what would make sense. That means you're the only person who could even hope to estimate the difficulty. Plus it would be a fair bit of work that nobody else seems that interested in, so unless you're offering to pay, you're the only one motivated to do the work. But perhaps, if you presented your results, they would be interesting enough for others to adopt.
Yes, but the fact is they would not appreciate my work because they do not appreciate it now. You might appreciate it but the fact is, people that bitch and complain about someone saying they have a problem with something and that "Do it my way attitude" are people who don't appreciate other peoples work, they only use it to further their own self. So, since I don't have to implement it, and because it is not a huge problem, I won't. Screw the assholes who try to shut down people and progress just because they are assholes(and who have no good reasons). It's one thing to debate a topic to find the best solution and it's another to try to shut it down based on an irrelevant argument. You know, not everything is complex: What is proposed here does not change the source any one bit. It only adds to it. It is basically inheritance(or a product). It doesn't distort the code(e.g., map it to a random alphabet) nor does it introduce any bugs. All it can do is add bloat. That is it! So, what they are bitching about, really, is they don't want bloat. But they can't see that because they are only conformist and they don't want anything to interfere with them conforming. But see, the problem with bloat is not necessary a problem. It is only a problem if the bloat is not useful. E.g., a class inheriting another class is adding bloat, so to speak. So, the issue should be how much bloat, how to control the bloat, and how to make the bloat useful... But guess what? No relevant discussion on these meaningful issues of the problem(the ones that, if they could be solved would solve the problem for everyone within reason) because they shut down the argument with there authoritative and mindless drivel. So, no, I will not help out, it's obviously no one wants help. I do have to do a risk analysis assessment because it does cost me my time. What I see is that I won't invest it because I won't invest in people with such attitudes which further helps them along and only generally strengthens their attitudes(because it must be working, right?). I will not play the shit slinging game. You or others will think I am slinging shit because I don't conform, but it's precisely why I am not slinging shit, because I am not conforming to the shit slingers. Of course, that assumes I am not a shit linger but it does prove that only one side slings shit. I let the historical record be my proof of who slings shit. They should be easy to spot because they have the smelly hands. A question I propose to you is that if a shit slinger slings shit at someone and that person throws the shit back at the original shit slinger, are they too a shit slinger? If so, are they equally culpable?
Sep 08 2018
parent Sjoerd Nijboer <dlang sjoerdnijboer.com> writes:
On Sunday, 9 September 2018 at 04:59:08 UTC, Josphe Brigmo wrote:
 Yes, but the fact is they would not appreciate my work because 
 they do not appreciate it now.
I can't really argue against that logic. But then again, I fail to see when such a situation would apply. I personally use the tortoisesvn diff viewers bound to hotkeys to help me with this, giving me perfect date and revision tracking + commit messages. Like you said, you might not have access to internet but git has the full history on your local repo and thus allowing you to do this. My personal preference is with mercurial, but this this works with pretty much any source control system that has a local repo and a working directory.
 All it can do is add bloat. That is it!
No one here wants more bloat, and that's what they're scared of. And that's why a usecase for this proposal is so much wanted.
Sep 09 2018
prev sibling parent krzaq <dlangmailinglist krzaq.cc> writes:
On Sunday, 9 September 2018 at 01:27:06 UTC, Josphe Brigmo wrote:
 This has nothing to do with git. People think git is the end 
 all be all. What if git is not available, then what? It's 
 moronic to think that one has to use one or the other when both 
 options are available and both only add information.
What do you mean by "git not being available"? The program? You'll sooner have git on a system than a compiler. The repository? Then the same argument can be said for the sources. And if you say mirror, so will I.
Sep 09 2018