Use a comment in code as revision tracking while using SVN



  • Continuing the discussion from Do you write a monthly report in a Microsoft Word file every month?:

    @Ascendant said:

    @WPT said:
    It just shows that the management realized that timesheets in Software development is a :wtf:

    Yeah... don't we work in software development? where we would put in a system that does the repetitive work for you?

    So now I'm in a different project( a third one since I first started working here in November 2015).

    Along with the anal tables and the usual ridiculous schedule and approach,
    now I see this.

    /**

    • 프로그램 ID :
    • 프로그램 한글명 : [some description]
    • 프로그램 소스명 : [something]Controller.java
    • 최초 생성일 : 2015. 10. 20
    • 최초 생성자 : [person name]
    • 최 종 버 전 : 1.0
    • 상세 설명(로직)
      • [description]

    • 수정이력
    • --------------------------------------------------------------------------------------------
    •  변경일			작성자		버전					변경내용                                       </br>
      
    • --------------------------------------------------------------------------------------------
        1. 20 [person name] 1.0 최초작성
    • --------------------------------------------------------------------------------------------

      */

    What it says is

    • programme(?) ID
    • programme name in Korean
    • programme source name (meaning the file name:InundationEvalController.java)
    • the date this programme(file) is created
    • the person who created this first
    • version number(!)
    • detailed logic(?)- what this does
    • and a log of changes

    Are each individual java files called a programme? I keep seeing this with code written by Koreans.

    And is it normal to keep a log within your source code in the form of a comment along with the above information?


  • area_can

    I haven't seen a log in comments before...unless it's for some ancient/complex/critical section that everyone needs to understand before touching.


  • Notification Spam Recipient

    Unfortunately, in my workplace it's not only expected to have this kind of thing in each file, but highly frowned upon if you don't.
    Despite the change history showing a required work item, and who did it and when and a comment why. And it being logged to the JIRA ticket. And iterated again on the process Review Board notes during deployment.

    This comment requirement is even needed for ad-hoc requests.



  • In Java, it's not uncommon to use Javadoc to keep certain data such as the author, the version, etc... in the file.

    ...but having the changelog in the file? Nope nope nope.



  • @powerlord said:

    In Java, it's not uncommon to use Javadoc to keep certain data such as the author, the version, etc... in the file.

    And it's not in the javadoc format.



  • @Ascendant said:

    programme

    Computer program and television programme... probably someone lookup a different word on web.



  • @Ascendant said:

    And is it normal to keep a log within your source code in the form of a comment along with the above information?

    Some older programs at my work do it but not all. It is frustrating because you can't trust everything to be there (someone doesn't update the log with a change they made), but my work has also repeatedly changed source control systems (including upgrading versions of TFS) without preserving the change logs. So it is annoying and stupid, but can protect at least notes on changes from other annoying and stupid things.


  • Discourse touched me in a no-no place

    @powerlord said:

    but having the changelog in the file

    IME that's common for places that don't use source control. It's still a :wtf: though.



  • We used to use pvcs or whatever, and I'm told that's why they show up in our old files, because that's how it tracked some things. Its pretty weird.


  • Discourse touched me in a no-no place

    @powerlord said:

    In Java, it's not uncommon to use Javadoc to keep certain data such as the author, the version, etc... in the file.

    Isn't that what version control keyword substitution is for? Or do you mean the whole history and not just the last person to touch that file?

    In other news, there's one person at ours that does this "pseudo change-log in comments at the top of the file." On 'his programs.' He, for some strange reason doesn't do it on other stuff he changes.

    I'm tempted to simply delete them, but can't justify it unless I have another reason to modify those files...



  • @FrostCat said:

    don't use source control

    I only cleaned up a few .bak files today, remaining from the bad old days. Also a .orig file someone committed after fixing a merge conflict!



  • @PJH said:

    version control keyword substitution

    We accidentally had the equivalent of

    header('$Rev: 1234$');

    In our code. It was actually a lot more subtle than that, it looked like a comment but that's a whole other WTF...

    In changing from svn to git this becomes

    header('$Rev$');

    Which is a http (CGI) syntax error. Which broke a bunch of pages with 500 internal server error.



  • @PJH said:

    Or do you mean the whole history and not just the last person to touch that file?

    Even whole history can be done via keywords in Subversion (and CVS).



  • I've seen these headers used for revision tracking before VCS became the norm 😋 the simple old ways. In the last decade I've only ever encountered this type of header with people who I'd judge to be sloppy programmers.



  • @Ascendant said:

    is it normal to keep a log within your source code in the form of a comment along with the above information?

    We have done it in 2 of the 3 very large companies I have worked for in the Enterprise space. Yes, "SVN blame" exists, but it can be nice to just have the comments and dates in the code itself for easy reference. Your mileage may vary though, and there are plenty of shops that forbid the practice outright ¯(°_o)/¯



  • I would say no, it's not normal. Comments like that are better served by other, external, systems (bug trackers, documentation, etc). This looks like the kind of thing Samsung might implement, because it's stupid, ugly, and totally not how a sane person would do that task (just like all of their code, products and services) so if those Koreans are working for Big S then it's probably just corporate policy.



  • Do any modern version control systems actually support those?



  • In the student information system I work on, all the vendor's stored procedure definitions have a large comment block at the top that describes what the sproc does, when it was originally written and by whom, as well as notes on every revision ever made to that sproc. There are inline comments, too, but the block comment is very helpful because us customers don't have access to their version control system.


  • I survived the hour long Uno hand

    We have a few of those from before we got version control.


  • Discourse touched me in a no-no place

    @Bulb said:

    Even whole history can be done via keywords in Subversion (and CVS).

    It came from the older system RCS. CVS was basically network-aware RCS (with some good practices enforced). $Log$ was always a bad idea, unless merge conflicts are your idea of a good time.

    It was quite nice to have $Revision$ and $Id$ as a way to stamp builds, but we can do that easily enough during the build process itself, and the concepts they use make no sense in a DVCS (where version identifiers are non-sequential and not structured).



  • @BaconBits said:

    stored procedure

    Stored procedures are the sore thumb of version control. Not everybody has learned to keep versioned migration scripts around and there is no version control in databases themselves. So in databases it is still 1970 and keeping version comments still makes sense there.

    @powerlord said:

    Do any modern version control systems actually support those?

    The simple keywords yes, but I couldn't find $Log$ anywhere. Not even Subversion, making the question whether Subversion counts as modern irrelevant.

    @Bulb said:

    Even whole history can be done via keywords in Subversion (and CVS).

    So actually I have to correct myself. It could last be done in CVS.

    @gleemonk said:

    In the last decade I've only ever encountered this type of header with people who I'd judge to be sloppy programmers.

    People who failed to mend their ways in 44 years can rightfully be considered sloppy programmers indeed. Applies similarly to organizations.

    @dkf said:

    $Log$ was always a bad idea, unless merge conflicts are your idea of a good time.

    Indeed. I vaguely recall that unlike the other keywords, it actually worked by adding the comments in the file, so the old logs had to be kept and could indeed cause conflicts. I am not sure how many people understood branches in CVS though, so in practice most probably got away with it, because they didn't merge.

    @dkf said:

    It was quite nice to have $Revision$ and $Id$ as a way to stamp builds

    Actually, that never ever worked. CVS&co.¹ revisions were file-specific, so you'd only get that one file's version in there. So you'd have had to collect the expansions from all sources to know what was built². Then when Subversion introduced repository-wide revision ID, it defined the keywords to expand to the last revision that file was modified in anyway, because otherwise it would have to rewrite all files even if they were not modified when updating and that would be just as silly as it sounds. In fact, the revision does not even have to be parent of the current revision, because in presence of merges, the file may sometimes have the same content, but different last modified revision on different branches and it is not rewritten when switching between such branches either (at least in Git; not sure if Subversion does).

    @dkf said:

    but we can do that easily enough during the build process itself

    No, it has to be done during the build process².

    @dkf said:

    and the concepts they use make no sense in a DVCS (where version identifiers are non-sequential and not structured).

    Don't generalize. Some DVCS do have sequential revision identifiers.

    There are two approaches, with the numeric identifiers being aliases to the underlying unique identifiers:

    1. Mercurial has numeric revision aliases, which are assigned in the order the revisions are stored in the repository. Therefore these aliases are stable, monotonically increasing, but specific to the particular repository.
    2. Bazaar has numeric revision aliases based on traversal of the revision tree. IIRC the leftmost ancestry is numbered sequentially from the initial commit and the merged branches get hierarchical numbers similar to how CVS numbered revisions. These aliases work on all repositories with the same branch, but some revisions get renumbered after merge. E.g. you commit revisions 212, 213 and 214, but when they get merged in mainline, they'll get renumbered to 211.1.1, 211.1.2 and 211.1.3 (or perhaps 211.3.1, 211.3.2 and 211.3.3 if two other branches based on 211 got merged earlier. Revisions in mainline are stable as long as you are careful and always merge branches to mainline and not mainline to branches (merge is commutative operation except for revision identifier).

    And of course, the revision IDs returned by git describe, which are almost stable, but only mostly numeric (the -gxxxxxxxx suffix is needed to disambiguate and to actually find the revision).


    ¹ Some time around 2006, in my former job, I was made to use Rational ClearCase. It was a monstrous abomination, a CVS-style model of files with independent versions beaten to support moving files and mostly working merging. I don't remember whether it had keywords (I didn't try to use them), but as a checkoutview could include about any combination of file versions³, I created a script, that labelled the versions used for each release build. The script took, on the not so big view, about quarter an hour. On local network.

    ² Actually, ClearCase came with a special version of make (IIRC it was called omake), that could generate the “bill of material”, a list of file versions used for build. I did not try to use it, because we were building with Visual Studio (6.0 and Embedded 4.0 back then (yes, 8 years old versions)) and writing a make-based build, and especially keeping it in sync with the VS developers used, would have been a nightmare.

    ³ Besides being slow as Molasses™, the biggest :wtf: of ClearCase was the “config spec”. That was a configuration blob (it was not in a file, it was fed to the client and it kept it somewhere inside) that specified which revisions of which files you should see. And you could specify absolutely anything: branches, labels, particular revisions, dates, and you could specify it for whole view, specific directories, specific files, wherever they were. And if you specified a branch, the files that did not have it would ignore it and use the next rule. All in all, you could get any combination of content by changing that abomination. And of course, being hidden somewhere in the client, it was not versioned and not even easily versionable as you had to make sure manually that the selected configspec matches the versioned file prescribing it (besides the obvious chicken-and-egg problem).

    So I pushed that all config specs should just be a branch and a label from which it is created (the branch was only created on each file as you first checked it out for editing, so a base label that existed on all files was needed). I knew version control⁵, in general, probably best of the team and the team leader knew it, so that's what we did in our part. The components developed in other departments often came with long, complicated config-specs though.

    ⁴ Another policy I pushed was that we shall always use non-exclusive checkouts and it generally made things much smoother, because we didn't have to constantly hunt down colleagues to ask them what they are doing on file X and if they could please check it in. But most people (and even more so managers, many of whom that stopped programming 35 years earlier) feared merging like the devil a cross.

    There were two projects, where we appreciated the exclusive checkouts, though: one, which we implemented in Adobe Creative Suit 3, which stored all its data in a binary blob, and one, which we implemented in Rational Rhapsody, where the UML diagrams were stored in text format, and the (huge) model was even spread across multiple files, but the absolute positions tended to change all the time, making it almost impossible to merge anyway.

    ⁵ At the time, 2006, Git was still hot from the oven (Git, Mercurial and Bazaar all started in 2005), but I used CVS, then Tom Lord's Arch (later GNU Arch) since it came out in 2001 and SVK (came out in 2003) for integration with Subversion (which did not support 3-way merge as of 2006, but SVK provided it for it). And meanwhile I learned Patch Algebra (Patch Theory) from Darcs, though I've never used Dacrs itself (the original pages about Patch Theory were IMO better than the ones you find on Darcs wiki now).



  • @Ascendant said:

    programme source name (meaning the file name:InundationEvalController.java)

    There's a comment in the source file stating the file's own filename? That's super retarded.



  • @Ascendant said:

    And is it normal to keep a log within your source code in the form of a comment along with the above information?

    I remember working in some super-ancient codebase where the VCS was configured to add the checkin notes to the top of each file as a comment. That got ugly fast...



  • @tar said:

    There's a comment in the source file stating the file's own filename? That's super retarded.

    Yeah I don't understand along with the terminology to call each source file a "programme".


  • Discourse touched me in a no-no place

    @tar said:

    There's a comment in the source file stating the file's own filename? That's super retarded.

    No, super retarded is when there's a comment in the source file with the file's own filename, and then someone clones the file to do something slightly different but doesn't change the commment!



  • Perhaps it is a secret plot to make the other company reveal where they violated copyright.
    Actually, it might even occasionally work. There is one small problem though; the comments don't make it to the product.


  • Discourse touched me in a no-no place

    @Bulb said:

    There are two approaches, with the numeric identifiers being aliases to the underlying unique identifiers:

    So they're aliases, not identifiers. The mercurial approach is moderately awkward since what you've got and what I've got might not agree, which is :wtf: since that's the whole point of putting the ID in, and the bazaar approach is crazy since they depend on people never ever fucking up for stability. 😆 The other DVCSs don't try to pretend that things are as nice as that, and expose the true IDs.



  • Mercurial and Bazaar have a different approach that Git. In Git ideas with irreconcilable corner cases were dismissed as bullshit, stupid, idiotic and such (Linus never went far for a strong word) and if there was popular demand, a better defined solution was sought, which is how the rename detection or the advanced revision specifiers were created.

    In Mercurial and Bazaar on the other hand they've beaten the idea into somewhat working state instead. Sometimes whole concepts were built on poorly defined ideas. I am not sure whether it is still the case, but Bazaar used to use a "weave" format, which makes it easy to do blame annotation, because it was seen as important feature. Needless to say it didn't perform all that great.


  • Discourse touched me in a no-no place

    Git has other things wrong with it, most notably its strong fascination with history rewriting and its very hostile UI. It's possible (and easy!) to get yourself in a very bad mess with git.



  • @FrostCat said:

    No, super retarded is when there's a comment in the source file with the file's own filename, and then someone clones the file to do something slightly different but doesn't change the commment!

    Well yeah, having the file's filename in a comment will either be:

    678767876567. Stating the obvious, or
    567856767. Wrong.

    In either case, it hardly seems worth the effort...



  • @dkf said:

    strong fascination with history rewriting

    The process that requires that predates Git by at least 10 years and since rebase appeared in Git, Mercurial and Bazaar got extensions to do it as well, because clearly there are teams and projects that consider it very valuable. And for that certain approach to reviews, it is.

    @dkf said:

    very hostile UI

    Yeah. The team totally sucked at UI. However well they prevented poorly defined ideas getting in, anything would get bolted on the UI if you provided a use-case for it without much planning and overall picture, leading to the maze of twisty little commands, all alike.

    @dkf said:

    It's possible (and easy!) to get yourself in a very bad mess with git.

    It is usually easy to go back and redo it, but of course only if you notice before publishing.

    Just not long ago colleague asked me to help in fixing a problem. He was doing a merge and there were some binary blobs that conflicted. And he new he could just take the local versions. So he aborted the merge and restarted it with resolution. Except instead of git merge -X ours he wrote git merge -s ours and reverted everything. And of course he noticed just after he pushed it.

    To be honest, noticing that the first ours in the documentation is suboption of recursive strategy from the two character indent is almost impossible. And there is another ours way further that is actually a strategy, so your mistake is not caught, but instead git silently does totally wrong thing.


  • Discourse touched me in a no-no place

    @Bulb said:

    To be honest, noticing that the first ours in the documentation is suboption of recursive strategy from the two character indent is almost impossible. And there is another ours way further that is actually a strategy, so your mistake is not caught, but instead git silently does totally wrong thing.

    Ugh. That's nasty. Even though there's a specific paragraph calling people's attention to the fact that there's a difference, it's still ever so easy to overlook. And someone thought that this was a good idea.

    Oh well, provided the server shared repository is able to do non-FF commits at all, it'll be fixable as you can use git reflog (or a good GUI) to find out what has gone wrong and reset things back to sanity. Fiddly but possible, provided nobody's configured things to be asinine.



  • @Bulb said:

    git merge -X ours he wrote git merge -s ours

    You guys are wizards, right?

    I've never seen any senior actually give git commands in the prompt.
    We just all use Subclipse.

    How do you manage to know all that?
    How many miles have you got under your belt?



  • @dkf said:

    Oh well, provided the server shared repository is able to do non-FF commits at all

    Our shared repository has insidious configuration, which allows me to non-FF any branch, but others can only non-FF their own branches (everybody has their own namespace, courtesy gitolite's USER rule).

    But we chose not to FF this. Simply revert to before the merge, do the merge properly, then merge -s ours the botched merge to make it FF and push.

    @Ascendant said:

    I've never seen any senior actually give git commands in the prompt.

    My long time boss was a huge enemy of command-lines. When we used ClearCase, and then Subversion, he always only used the GUI and always insisted on having integration with the IDE available and set up and that. But now that he works (in another company) with Git, he uses command-line too. Because nobody managed to wrap the hairy but powerful git interface in an actually practical GUI yet.

    @Ascendant said:

    How many miles have you got under your belt?

    Me? Many. Read the footnotes in the earlier post ;-).


  • Discourse touched me in a no-no place

    @Bulb said:

    Because nobody managed to wrap the hairy but powerful git interface in an actually practical GUI yet.

    Eclipse's egit is quite reasonable for simple to moderate tasks (certainly including fixing the mess you were in). Advanced gitting requires the command line, a psychiatric examination, and a good serving of spirits.



  • @dkf said:

    Eclipse is quite reasonable

    No, it isn't. At least not when developing in C++. And since the primary development platform was Windows (CE), we were always mostly tied to Visual Studio anyway.


  • Discourse touched me in a no-no place

    @Bulb said:

    No, it isn't. At least not when developing in C++. And since the primary development platform was Windows (CE), we were always mostly tied to Visual Studio anyway.

    Oh, I'm not arguing that Eclipse overall is reasonable. But it's git integration is actually competent.



  • That's all nice and everything, but rather useless for people who can't use the rest of the thing.


  • Discourse touched me in a no-no place

    @Bulb said:

    That's all nice and everything, but rather useless for people who can't use the rest of the thing.

    Hey, you were the one claiming that there was no such thing as a good GUI for git. I proved you wrong, but then you threw in a bunch of requirements that you previously hadn't mentioned. Are you management or a customer or something?


  • ♿ (Parody)

    @dkf said:

    The mercurial approach is moderately awkward since what you've got and what I've got might not agree, which is :wtf: since that's the whole point of putting the ID in

    It's super handy to use while working on stuff. You can, for instance, bisect using the numbers so it's relatively obvious where you are in the history (like svn). For anything that you're doing only locally (which is really most stuff), you can just use the number instead of the hash.

    @dkf said:

    The other DVCSs don't try to pretend that things are as nice as that, and expose the true IDs.

    Mercurial gives you both.



  • Dude. No.

    You can't put "good GUI" and "Eclipse" in the same sentence.

    Eclipse is written in Java. It's forever disqualified from being a "good GUI" in any facet.

    You might like it. Fine. That doesn't mean it's good; that means your standards are so low they're scraping the bottom of the barrel.


  • Discourse touched me in a no-no place

    You're just wrong this time. You've managed to write an entire message without being right once except, partially, for the sentence “Eclipse is written in Java.” which is the one thing in there that is factual. (I don't like Eclipse, but I've tried the alternatives and like them less.) You're so bigoted that you never look for the truth in what others say when they conflict with your preconceptions at all. Bah, you should try politics!

    EGit, the Eclipse plugin for git support (a default plugin to Eclipse these days), does do a better job of putting lipstick on the bloated pustule-ridden sow that is git's UI than the alternatives I've seen.

    I'd still rather use something else. But not IntelliJ, NetBeans, or XCode. (The full version of Visual Studio isn't even available for Mac, and Visual Studio Code doesn't support the full list of languages that I'm currently using in my projects.) Nor would I use a plainer editor like vim for Java; I have done that in the past and it sucks a lot in a different way. You might argue that I should switch to using C#, but I would respond that you should fuck off (it'd be a lot of work and not actually be practically useful for my current job).

    I'm guessing that the authors of egit were using it for some other task, that they actually knew what git did, and that they made egit work for as many of the things that they could and hide as much shit as possible. It's certainly a lot better than the shit you get with github or (the marginally better) gitlab.



  • @dkf said:

    You've managed to write an entire message without being right once except, partially, for the sentence “Eclipse is written in Java.” which is the one thing in there that is factual

    That's the only bit I need to know the GUI is twice-boiled shit.


  • ♿ (Parody)

    @blakeyrat said:

    That's the only bit I need to know the GUI is twice-boiled shit.

    But knowing something and that something being right are not the same thing.



  • I once asked someone who claimed Java could be used to write a good GUI to put his money where his mouth was and show me one.

    He pointed me to uTorrent.

    Enough said.


  • ♿ (Parody)

    @blakeyrat said:

    Enough said.

    Yes, please stop.


  • Java Dev

    @tar said:

    I remember working in some super-ancient codebase where the VCS was configured to add the checkin notes to the top of each file as a comment. That got ugly fast...

    http://web.mit.edu/quentin/oracle/instantclient_11_1/sdk/include/oci.h

    over 500 lines of header comment.



  • @Bulb said:

    >Eclipse is quite reasonable

    No, it isn't. At least not when developing in C++.

    What's unreasonable about C++ work in Eclipse? From my (limited) experimentation with it, it was absurdly easy to knock up a project for a makfile project and launch the debugger. Code analysis was pretty good too -- you could even step through macro expansions in the UI, which was nice.

    Sure, VS is probably better overall (and I'm certainly more familiar with it), but at the time it wasn't free, and it still doesn't really run on not-Windows platforms. Eclipse seemed decent enough for my purposes /shrug



  • @blakeyrat said:

    He pointed me to uTorrent.

    uTorrent is written in Java? Perhaps you meant [s]whatever Azureus is being called these days[/s] Vuze?



  • Whatever. It was a really shitty bittorrent client.


Log in to reply