Re: Naming things
On 20/06/2015 10:27, Vladimir Panteleev wrote: Naming things There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton Hello, There has been a lot of recent debate regarding the names of some new functions recently added to Phobos. Mostly this concerns the good work of Walter Bright, and new functions which operate on ranges rather than strings. A few times, many people felt that the names could have been chosen better - in some cases, much better. This is not a singular occurrence, but a recurrent one: http://forum.dlang.org/post/ybbwpgmgsqvmbvoqh...@forum.dlang.org https://github.com/D-Programming-Language/phobos/pull/2149#issuecomment-42867964 So far, post-merge name changes have been rejected: https://github.com/D-Programming-Language/phobos/pull/3243 https://github.com/D-Programming-Language/phobos/pull/3426 Two examples of controversial name pairs: setExt/setExtension, and toLower/toLowerCase. These functions have the same functionality, but one of them is eager, and the other is lazy. Can you guess which is which? Can I guess which is which? I wouldn't guess, I would just look at the doc to figure it out! Think opening up a browser and looking up the function doc online is cumbersome/annoying? You're right, so just use an IDE that shows the DDoc of the function during code completion. Problem trivially solved. (Both DDT and Mono-D support this functionality) I would like to present a very similar case in another language, JavaScript. The String method has two functions with a similar name and functionality: substr and substring. If you were to search the web, you can find a multitude of confusion over these functions: http://stackoverflow.com/questions/3745515/what-is-the-difference-between-substr-and-substring https://nathanhoad.net/javascript-difference-between-substr-and-substring http://javarevisited.blogspot.com/2013/08/difference-between-substr-vs-substring-in-JavaScript-tutorial-example.html https://rapd.wordpress.com/2007/07/12/javascript-substr-vs-substring/ https://www.youtube.com/watch?v=OAameXW5r10 I think it's safe to say that it's one of JavaScript's many small warts. Javascript doesn't have a Javadoc/DDoc analogue, does it? So, not applicable. -- Bruno Medeiros https://twitter.com/brunodomedeiros
Re: Naming things
On Monday, 22 June 2015 at 19:43:30 UTC, Walter Bright wrote: On 6/22/2015 7:22 AM, Vladimir Panteleev wrote: It seems everyone in this thread is in agreement, so what would be the next step? It is a time-sensitive matter as preparations for 2.068's release are already underway. After two pings I failed to engage Walter Bright in this conversation; I don't think I should just reopen my pull request a second time, and I've been reading these things, but not engaging in them because it seemed best to let everyone have their say without interference from me. Thanks. I followed up on the proposal from yesterday's IRC discussion with Andrei: http://forum.dlang.org/post/rvaguhviuldknnqkt...@forum.dlang.org I fear that if I merge someone else's pull request, I just might get my commit privileges revoked :) I don't know where I get this terrible reputation - I've never revoked anyone's commit privileges. And certainly not yours - your track record of contributions and positive influence on D is impeccable. Ah, thank you, and sorry about that - it was a joke regarding last week's events...
Re: Naming things
On Monday, 22 June 2015 at 16:06:33 UTC, Kelet wrote: I agree with Vladimir -- There should be a naming convention for identifying whether a function is eager or lazy. Learning a naming convention once and applying it repeatedly is a better process than repeatedly referencing documentation. A programming language should have built-in functionality that is named in such a way that it clearly expresses its intent. For newbies, it can be very off-putting to be introduced to a language where this is not the case. Perhaps some veterans of the D language can't clearly see this. There is no good reason that the new introduction of built-ins should not follow a well-defined naming scheme. I'd actually go a bit further and deprecate old functions that do not meet the scheme and phase them out over time. Bikeshedding is arguing over trivial naming schemes. Choosing to adhere to a naming scheme is not bikeshedding, IMHO. Thanks, Well put. I don't like how often I have to refer to the documentation. And I have been trying to use D for a while. A naming convention expressing intent should reduce the need for frequenting the documentation. This would be a welcome addition. Even at the cost of dusruptive change. Joseph
Re: Naming things
I agree with Vladimir -- There should be a naming convention for identifying whether a function is eager or lazy. Learning a naming convention once and applying it repeatedly is a better process than repeatedly referencing documentation. A programming language should have built-in functionality that is named in such a way that it clearly expresses its intent. For newbies, it can be very off-putting to be introduced to a language where this is not the case. Perhaps some veterans of the D language can't clearly see this. There is no good reason that the new introduction of built-ins should not follow a well-defined naming scheme. I'd actually go a bit further and deprecate old functions that do not meet the scheme and phase them out over time. Bikeshedding is arguing over trivial naming schemes. Choosing to adhere to a naming scheme is not bikeshedding, IMHO. Thanks,
Re: Naming things
On Saturday, 20 June 2015 at 09:27:16 UTC, Vladimir Panteleev wrote: Two examples of controversial name pairs: setExt/setExtension, and toLower/toLowerCase. These functions have the same functionality, but one of them is eager, and the other is lazy. Can you guess which is which? Yikes! That should have never passed scrutiny in the pull request. I'm sorry I didn't see it, as I would have voiced opposition to it. I only just started monitoring Phobos this week. My work doesn't really require me to use Phobos much. It would be unfortunate if we were to have such warts in D, so I think we should at least not outright reject PRs which fix them. I totally agree. I was really excited about D a year and a half ago, and what really lit my fire was Andrei's talk about Operational Professionalism at DConf 2013. At that time, I thought, Wow, this community really cares about getting things right. How naive of me :) But, I'm still here...perhaps foolishly. It makes me disappointed to see contributions that dot the 'i's and cross the 't's get turned away and belittled. But, I don't think there's anything I can do about it, and although you've made an excellent argument, I've gathered enough wisdom in my time here to make a reasonable prediction of the outcome. I also believe the relatively little response you've received in this thread is likely not an indication that few care, or that few support your argument, but rather that they've seen it before, and they know how it ends. Mike
Re: Naming things
On Saturday, 20 June 2015 at 09:27:16 UTC, Vladimir Panteleev wrote: Two examples of controversial name pairs: setExt/setExtension, and toLower/toLowerCase. These functions have the same functionality, but one of them is eager, and the other is lazy. Can you guess which is which If I had to hazard a guess, I'd go with the shorter one is lazy, but that presumes I'd notice there were two nearly-identical functions in the first place and pick up on the not-well-conveyed implication that one is lazy and the other is not. That's a Bad Thing. And it's a bad thing everyone seems to be tip-toeing around, too. None of the suggestions I've seen so far really call out to me hey, this is lazy and has a non-lazy counterpart. Would it be so wrong to add lazy to the beginning or end so it's super obvious at a glance with zero cognitive overhead? -Wyatt
Re: Naming things
On Monday, 22 June 2015 at 11:45:31 UTC, Wyatt wrote: On Saturday, 20 June 2015 at 09:27:16 UTC, Vladimir Panteleev wrote: Two examples of controversial name pairs: setExt/setExtension, and toLower/toLowerCase. These functions have the same functionality, but one of them is eager, and the other is lazy. Can you guess which is which If I had to hazard a guess, I'd go with the shorter one is lazy, but that presumes I'd notice there were two nearly-identical functions in the first place and pick up on the not-well-conveyed implication that one is lazy and the other is not. Well, you'd be wrong. Although setExt is the lazy version of setExtension, toLowerCase is the lazy version toLower. Who needs consistency, eh? And it's a bad thing everyone seems to be tip-toeing around, too. None of the suggestions I've seen so far really call out to me hey, this is lazy and has a non-lazy counterpart. Would it be so wrong to add lazy to the beginning or end so it's super obvious at a glance with zero cognitive overhead? Just to reiterate, I want to stress that finding a perfect name is of secondary concern to deciding to change the name in the first place. A big part of the argument against renaming things is look how much debate there is about what it should be called, it's obvious there is no consensus, let's just leave things as they are.
Re: Naming things
On 22/06/2015 7:17 p.m., Mike wrote: On Saturday, 20 June 2015 at 09:27:16 UTC, Vladimir Panteleev wrote: Two examples of controversial name pairs: setExt/setExtension, and toLower/toLowerCase. These functions have the same functionality, but one of them is eager, and the other is lazy. Can you guess which is which? Yikes! That should have never passed scrutiny in the pull request. I'm sorry I didn't see it, as I would have voiced opposition to it. I only just started monitoring Phobos this week. My work doesn't really require me to use Phobos much. It would be unfortunate if we were to have such warts in D, so I think we should at least not outright reject PRs which fix them. I totally agree. I was really excited about D a year and a half ago, and what really lit my fire was Andrei's talk about Operational Professionalism at DConf 2013. At that time, I thought, Wow, this community really cares about getting things right. How naive of me :) But, I'm still here...perhaps foolishly. It makes me disappointed to see contributions that dot the 'i's and cross the 't's get turned away and belittled. But, I don't think there's anything I can do about it, and although you've made an excellent argument, I've gathered enough wisdom in my time here to make a reasonable prediction of the outcome. I also believe the relatively little response you've received in this thread is likely not an indication that few care, or that few support your argument, but rather that they've seen it before, and they know how it ends. Mike I haven't commented yet but you have half hit a nerve for me. Okay so, I'm in agreement about the point being made 100%. But there isn't really anything I can _do_ about it. I don't really review Phobos PR's. Just a thought, add a checklist to CONTRIBUTING.md on Github and have this as one of them for function/method names. It probably just slipped peoples minds. Problem solved.
Re: Naming things
On Monday, 22 June 2015 at 07:25:19 UTC, Rikki Cattermole wrote: But there isn't really anything I can _do_ about it. See the sentence before that. I don't really review Phobos PR's. That's not at all what I said.
Re: Naming things
On Saturday, 20 June 2015 at 09:27:16 UTC, Vladimir Panteleev wrote: Two examples of controversial name pairs: setExt/setExtension, and toLower/toLowerCase. These functions have the same functionality, but one of them is eager, and the other is lazy. Can you guess which is which? I've taken a look at the offending PR (https://github.com/D-Programming-Language/phobos/pull/3370). Unfortunately, it was only up for review for about a day before it was merged, and only one person commented on it before it was merged. Given that some PRs are currently rotting for months, I hate to say that PRs should remain open for a minimum amount of time, but that's what I'm saying. We're all very busy, so give PRs a few days for reviewers to get to them. IMO, that PR should have never passed scrutiny, and probably wouldn't have if it was given a little more time. Mike
Re: Naming things
On Monday, 22 June 2015 at 11:45:31 UTC, Wyatt wrote: None of the suggestions I've seen so far really call out to me hey, this is lazy and has a non-lazy counterpart. Would it be so wrong to add lazy to the beginning or end so it's super obvious at a glance with zero cognitive overhead? -Wyatt This would be my preferred option. When C# introduced asynchronous counterparts of existing methods, they appended Async to the names, which seems to have worked out well - eg, Wait/WaitAsync, Read/ReadAsync. So we'd have setExtension/setExtensionLazy etc.
Re: Naming things
On Saturday, 20 June 2015 at 20:43:21 UTC, Nick Sabalausky wrote: On 06/20/2015 05:27 AM, Vladimir Panteleev wrote: [...] +1kazillion +1 ;)
Re: Naming things
On 6/22/2015 7:22 AM, Vladimir Panteleev wrote: It seems everyone in this thread is in agreement, so what would be the next step? It is a time-sensitive matter as preparations for 2.068's release are already underway. After two pings I failed to engage Walter Bright in this conversation; I don't think I should just reopen my pull request a second time, and I've been reading these things, but not engaging in them because it seemed best to let everyone have their say without interference from me. I fear that if I merge someone else's pull request, I just might get my commit privileges revoked :) I don't know where I get this terrible reputation - I've never revoked anyone's commit privileges. And certainly not yours - your track record of contributions and positive influence on D is impeccable.
Re: Naming things
On Monday, 22 June 2015 at 07:17:56 UTC, Mike wrote: It makes me disappointed to see contributions that dot the 'i's and cross the 't's get turned away and belittled. But, I don't think there's anything I can do about it, and although you've made an excellent argument, I've gathered enough wisdom in my time here to make a reasonable prediction of the outcome. I also believe the relatively little response you've received in this thread is likely not an indication that few care, or that few support your argument, but rather that they've seen it before, and they know how it ends. I agree with this, and given all the complaints by the leadership about lack of contribution, it's shocking to see the same individuals constantly putting down the work of others as not being of sufficient importance.
Re: Naming things
On Monday, 22 June 2015 at 14:09:11 UTC, Jonathan M Davis wrote: Naming stuff is hard, but there is definitely a cost to poor names, which is something that Walter rarely seems to acknowledge, especially if it means changing an existing name - but since this is about functions that haven't even been released yet, I wouldn't think that it would be as big a deal to change them. It seems everyone in this thread is in agreement, so what would be the next step? It is a time-sensitive matter as preparations for 2.068's release are already underway. After two pings I failed to engage Walter Bright in this conversation; I don't think I should just reopen my pull request a second time, and I fear that if I merge someone else's pull request, I just might get my commit privileges revoked :)
Re: Naming things
On Monday, 22 June 2015 at 11:51:27 UTC, Vladimir Panteleev wrote: Just to reiterate, I want to stress that finding a perfect name is of secondary concern to deciding to change the name in the first place. A big part of the argument against renaming things is look how much debate there is about what it should be called, it's obvious there is no consensus, let's just leave things as they are. I think that it's abundantly clear that the names are not well chosen. It's a guarantee that you're going to have to look at the docs to have any clue as to which is lazy and which isn't. I completely agree with adding lazy versions of the functions like Walter is doing, and our naming situation sucks on some level given that we have never named things based on whether they were lazy or not, and so there really is no way that all of the names in Phobos are going to be consistent in that manner (not without breaking more code than we're willing to break anyway), but the new names do seem particularly bad. A function that starts with set doesn't even sound like it's lazy anyway - not to mention, wasn't setExt the old function that std.path had before it was revamped? Naming stuff is hard, but there is definitely a cost to poor names, which is something that Walter rarely seems to acknowledge, especially if it means changing an existing name - but since this is about functions that haven't even been released yet, I wouldn't think that it would be as big a deal to change them. - Jonathan M Davis
Re: Naming things
On Saturday, 20 June 2015 at 09:27:16 UTC, Vladimir Panteleev wrote: Naming things There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton Hello, There has been a lot of recent debate regarding the names of some new functions recently added to Phobos. ... I'd like to note my support for consistent/standardized naming (especially with regards to `withExtension`/`setExt`). As an end-user of D, it's very important to me that a precedent be set for naming prior to D releases - it means less time spent upfront perusing documentation, and less time spent trying to understand how a particular function works. When I'm viewing code in the wild, so to speak, time spent trying to understand byzantine names is time wasted. In this particular case, `withExtension` is objectively better than `setExt.` The `with` prefix indicates lazy operation - this is a much better cue as to the function's operation than the truncation of an already-existing name. Truncating the name will, without a doubt, lead to user confusion: these two functions have the same goal, but operate in fundamentally different ways, and the name should reflect this. The alphanumerical sorting argument has little validity, especially seeing as the See Also section serves the same purpose. I understand that the community's been beset with naming discussions for the longest of times - and yes, they can often be non-productive - but there are some cases in which it is very much worth the time choosing a better name. `setExt` is objectively confusing and uncommunicative of its actual functionality - and it can be fixed now, before it becomes a permanent wart. As a final note, naming conventions are very important for the end-user of a programming language. If one goes with a 'pick the first name that works' approach, the result is a very unproductive, contradictory language; an extreme example of this can be seen in PHP, where programmers often have to consult the documentation for *every* function to find the correct name for every function. We have the ability to prevent that from happening here.
Naming things
Naming things There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton Hello, There has been a lot of recent debate regarding the names of some new functions recently added to Phobos. Mostly this concerns the good work of Walter Bright, and new functions which operate on ranges rather than strings. A few times, many people felt that the names could have been chosen better - in some cases, much better. This is not a singular occurrence, but a recurrent one: http://forum.dlang.org/post/ybbwpgmgsqvmbvoqh...@forum.dlang.org https://github.com/D-Programming-Language/phobos/pull/2149#issuecomment-42867964 So far, post-merge name changes have been rejected: https://github.com/D-Programming-Language/phobos/pull/3243 https://github.com/D-Programming-Language/phobos/pull/3426 Two examples of controversial name pairs: setExt/setExtension, and toLower/toLowerCase. These functions have the same functionality, but one of them is eager, and the other is lazy. Can you guess which is which? I would like to argue that these rejections were poorly argumented and should have been accepted. Although the names of these particular functions are the primary point of the post, I would like to also discuss the general policy of minor changes. I have discussed the issue at hand with Andrei Alexandrescu on IRC. Here are some points gathered: 1. The renames do not apply to code that appeared in a DMD release, thus they are non-breaking changes. As the actual code has been merged, the renames are not blocking anything either. 2. There seems to be some confusion regarding what counts as consensus. Walter Bright argues that there is no consensus regarding the new names. I would like to split this argument into two questions: a) Is there consensus that the current names are very bad, and should be changed? b) Is there consensus on which name to use? These two questions must not be confused. I think there is sufficient evidence that shows that everyone who has an opinion on the names, agrees that the current names are pretty bad. What the new names should be is of secondary importance, as long as the names are changed to any of the suggested names. 3. The main argument against allowing post-merge renames is that allowing one invites an infinite number of other minor changes. I think this is not a good argument, because: - In this particular case, there is unilateral consensus that the current names are objectively bad, and should be changed. There are no arguments that show that e.g. setExt is a better name than e.g. withExtension. I see no problem with not acting on renaming suggestions in situations when there is no consensus. - Naming things well matters. We need to treat renames in the same way as minor breaking changes. In the same way that we do not reject minor breaking fixes and improvements to the implementations of functions that have not yet been released, we should improve the naming of identifiers if there is consensus that the change is an improvement. 4. I have often heard the argument that bikeshedding distracts from getting actual work done, or variations of such. I think this argument is flawed. Discussions about minor things will continue regardless of whether small changes, such as renames, are rejected as a matter or policy or not. (Yes, this post is an example of this.) Yes, allowing some minor changes but not others will generate debate on why some changes were accepted and others not. Rejecting all minor changes does not prevent such debate from occurring, especially since there will always be exceptions (see e.g. std.meta). I would thus like to argue that the policy of no minor changes, even non-breaking should be reviewed. 5. Again, naming things well matters. An API with confusing or overlapping identifier names is a bad API. I've said this above but I want to say this again: we need to stop looking at renames as evil or as a waste of time, and look at them in the same way as (breaking) changes to the API / functionality. Just like API or functionality changes can be subjective in their usefulness, so can renames be controversial or overwhelmingly positive. I do not disagree that how well identifiers are named is a secondary concern to the functionality that they provide. But this does not mean that we should ignore the quality of the names, and furthermore, reject any attempts to improve them. 6. Concerning the naming itself. My involvement comes from when my PR to rename setExt to withExtension was closed. I would like to present a very similar case in another language, JavaScript. The String method has two functions with a similar name and functionality: substr and substring. If you were to search the web, you can find a multitude of confusion over these functions: http://stackoverflow.com/questions/3745515/what
Re: Naming things
On Saturday, 20 June 2015 at 09:27:16 UTC, Vladimir Panteleev wrote: I would like to present a very similar case in another language, JavaScript. The String method has two functions with a similar name and functionality: substr and substring. If you were to search the web, you can find a multitude of confusion over these functions: but see how you will hit some of that links by searching for javascript substr or something like it! what that gives is more popularity: everyone wants to write an article for such a hot, yet easy topic. thus, having the same naming in D inevitably leads to more articles about D, and to increased popularity!
Re: Naming things
On Saturday, 20 June 2015 at 18:46:45 UTC, Steven Schveighoffer wrote: I think the issue we are struggling with here is that: abbreviate - abbreviated This makes some sense. However, the past participle of set is set. So set the extension - a set extension doesn't work, because set doesn't change. Our enemy here is the English language :) If the original was named something like modifyExt, then modifiedExt would be fine. I would understand that if it was part of a consistent pattern for new names. However, judging by toLower/toLowerCase, there is none - and, if I understand Walter Bright's argument correctly, he argues that since we were not consistent in naming when creating std.algorithm, there is no reason to be consistent about it now. And my understanding of the pushback from Walter about renaming really has to do with avoiding breaking code for the sake of renaming. At this point (before setExtension has ever been released), it's what is the best name. No code should be broken, the renaming objection shouldn't apply. I'm 100% in favor of not having both setExt and setExtension to mean different but similar things. Just to clarify, it's still not too late to rename setExt. And 'with' doesn't work with every possible updated version, we have to work around the quirks of English here. I think just using different verbs/prepositions would work. For example, asLowerCase. But really, the egregious error is the slightly different yet identical names. It's like having setExt and set_ext mean different things. This also reminds me of std.regex vs. std.regexp. I never knew which one was the new version. At least that was temporary. This is going to be set in stone once 2.068 rolls out.
Re: Naming things
On 06/20/2015 05:27 AM, Vladimir Panteleev wrote: [...] +1kazillion
Re: Naming things
On 6/20/15 5:27 AM, Vladimir Panteleev wrote: Naming things There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton I think the issue we are struggling with here is that: abbreviate - abbreviated This makes some sense. However, the past participle of set is set. So set the extension - a set extension doesn't work, because set doesn't change. Our enemy here is the English language :) If the original was named something like modifyExt, then modifiedExt would be fine. And my understanding of the pushback from Walter about renaming really has to do with avoiding breaking code for the sake of renaming. At this point (before setExtension has ever been released), it's what is the best name. No code should be broken, the renaming objection shouldn't apply. I'm 100% in favor of not having both setExt and setExtension to mean different but similar things. withExt seems better, and reasonably informative. path.withExt(abc) - use this path, but with extension '.abc' And 'with' doesn't work with every possible updated version, we have to work around the quirks of English here. But really, the egregious error is the slightly different yet identical names. It's like having setExt and set_ext mean different things. This also reminds me of std.regex vs. std.regexp. I never knew which one was the new version. If there is some other idea besides setExtension (or some prefix of that), I think we should go with that. We could use some analog to 'set', like 'modifiedExt' or 'changedExt' if that sounds better. It just shouldn't be the same exact name, with differing levels of abbreviation. -Steve
Re: Naming things in Phobos - std.algorithm and writefln
On 2009-08-05 11:11:20 -0400, Daniel Keep daniel.keep.li...@gmail.com said: Java and, to a lesser extent, .NET have this serious problem where all of the names are needlessly long and verbose. This makes writing actual code tedious and annoying. No, I do not use an IDE and I shouldn't NEED autocomplete to be able to write code efficiently. I do Objective-C, so I know a lot about long names. :-) What's great about them is that they make the code a lot very readable (especially with Objective-C where methods read like a sentence). What's less great is that they're long to type. (An no I don't want to see sentense-long funciton names in D by the way, the D grammar isn't appropriate for that.) Also, making code longer means less of it fits on a line, less on a page and most critically of all: less in your brain. Look at legalese: it's incredibly accurate but also almost impossible to read. I've found that it takes so long to read a sentence that by the time you finish, you've forgotten what it was about. My take is that the sentenses are too long, not the actual words. Would the legalise be more readable if it were using abbreviated words? I believe it'd be worse. Same with code. If you put too much in a statement it'll become hard to decipher. Just because a name is unambiguous doesn't automatically make it good. writefln is a good name because the root indicates what it does it writes to something, the f comes from printf and ln is used in a few languages. You mean that a good name is one that begins with a word followed by half-conventions from various other languages merged together? That other languages use some other convention isn't really a justification for naming D functions against the D conventions. What's more, even if you don't know what those suffixes mean initially, because they're used *consistently*, once you learn it you can apply it all over the place. But can they be used consistently? In C, you have a lot of math functions having the suffix f, and it has nothing to do with them being formatted. Can we restrict the usage of the suffix f to mean formatted in the guidelines? Can we restrict the usage of the suffix ln to mean line? Also, that convention doesn't scale. There is a very limited number of short suffix. Either you'll start reusing them for other things, or you'll have a bunch of legacy functions using a short prefix and new functions with more explicit names. And best of all: it's short to type. [2] [2] And just to pre-empt it: this doesn't mean 'ofln' is a good name for an output function. Doesn't mean it's bad either; that depends on context. True indeed. But D allows symbol renaming in the import declaration. If you're going to use a function a lot, you can rename it to something shorter for a module. If you're not using it much, the long name will be more explicit. import std.stdio : ofln = outputFormattedLine; I'm tring to see how I can adapt the guidelines to accept this function (writefln) and I can't see any sensible rule I could add. Any idea? Short suffixes are good when applied consistently across multiple symbols.? Does this justify the sufix being lowercase. It's a different word after all. Why not writeFLn? Alternatively, writefln could be an exception to the rules, but then the exception would need a better rationale than it shouldn't look like Java. I mean, if Phobos makes unjustified exceptions to its naming conventions here and there for no good other reason than it looks good, it breaks the concistency and makes function names less predictable and less readable. As I indicated above, it's descriptive, consistent and short; a great name. I disagree, it's descriptive up to until fln. At least that's my opinion. Don't misunderstand me: I like writefln for it's shortness and because it's easy to write. But I don't see how I can justify the name without adding some arbitrary exceptions that look dumb. Perhaps I should just leave the names alone in Phobos and let Walter's style guide do the job. It says: Names formed by joining multiple words should have each word other than the first capitalized. which means you can write names as you like as long as it's not words concatenated together. Source: http://www.digitalmars.com/d/2.0/dstyle.html -- Michel Fortin michel.for...@michelf.com http://michelf.com/
Re: Naming things in Phobos - std.algorithm and writefln
Michel Fortin wrote: In std.algorithm, wouldn't it be clearer if splitter was called splitLazily or splitLazy? splitter is a noun, but as a function shouldn't it be a verb. makeSplitter or toSplitter perhaps? This is a specious argument. splitter's only purpose is to return an instance of a Splitter struct. You can't call it splitLazily or splitLazy because that implies that the function is doing work, when it really isn't. Following this line of reasoning, all structs should be renamed to verbs. makeSplitter is OK, but needlessly verbose. I think when you have a function whose only purpose is to construct something, or is strictly or conceptually pure, it's OK to use a noun for its name. And what about the array function? Wouldn't it be clearer if it was toArray so we know we're preforming a convertion? Same reasoning as above. toArray is also fine; it's possibly more in line with other conversion functions. As you know, I tried to write some guidelines[1] for naming things in D. Those guidelines looks well at first glance, but then you look at Phobos and you see that half of it use some arbitrary naming rules. Take writefln for instance: following my guidelines (as they are currently written) it should be renamed to something like writeFormattedLine. [1]: http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines I think that's a problem with the guidelines. Anyone trying to turn D into Java should be shot. It's not clear what fln means, true... until you look up ANY output function with a f, ln or fln suffix and then it's obvious. ... What does everyone thinks about all this? I think it's a good idea to have a good style guide; but rules only exist to make you think once before you break them. :)
Re: Naming things in Phobos - std.algorithm and writefln
Michel Fortin wrote: As you know, I tried to write some guidelines[1] for naming things in D. Those guidelines looks well at first glance, but then you look at Phobos and you see that half of it use some arbitrary naming rules. Take writefln for instance: following my guidelines (as they are currently written) it should be renamed to something like writeFormattedLine. [1]: http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines I think naming guidelines aren't a bad thing, but they can be taken too far. We use an automated tool at work to check code and today I was forced to change the name of some classes because they ended in Queue or Dictionary and fix the spelling of Http because it thought it was Hungarian notation.
Re: Naming things in Phobos - std.algorithm and writefln
On 2009-08-05 03:29:11 -0400, Daniel Keep daniel.keep.li...@gmail.com said: Michel Fortin wrote: In std.algorithm, wouldn't it be clearer if splitter was called splitLazily or splitLazy? splitter is a noun, but as a function shouldn't it be a verb. makeSplitter or toSplitter perhaps? This is a specious argument. splitter's only purpose is to return an instance of a Splitter struct. You can't call it splitLazily or splitLazy because that implies that the function is doing work, when it really isn't. I agree, those aren't very good names. Following this line of reasoning, all structs should be renamed to verbs. makeSplitter is OK, but needlessly verbose. I think when you have a function whose only purpose is to construct something, or is strictly or conceptually pure, it's OK to use a noun for its name. Perhaps this rule should be added to the guideline then. But as it was said countless times in the all the threads about properties, many nouns are also verbs in English, and they can easily create confusion in this situation. Calling directly the constructor of Splitter would be great, but alas you can't deduce struct template aruments from its constructor and have to rely on a separate function. makeSplitter is the less consusing one in my opinion. Altenatively, we could rename splitter to split. After all, the documentation says Splits a range using another range or an element as a separator. If you want an array, you write split(...).toArray(), or perhaps better would be to have the resulting range implicitly-casted to an array when needed (but are implicit casts still in the pipe now that we have alias this?). And what about the array function? Wouldn't it be clearer if it was toArray so we know we're preforming a convertion? Same reasoning as above. toArray is also fine; it's possibly more in line with other conversion functions. As you know, I tried to write some guidelines[1] for naming things in D. Those guidelines looks well at first glance, but then you look at Phobos and you see that half of it use some arbitrary naming rules. Take writefln for instance: following my guidelines (as they are currently written) it should be renamed to something like writeFormattedLine. [1]: http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines I think that's a problem with the guidelines. Anyone trying to turn D into Java should be shot. It's not clear what fln means, true... until you look up ANY output function with a f, ln or fln suffix and then it's obvious. Please, don't make unsupported accusations as an excuse to shoot people. Instead, you should say what you dislike about Java and explain why. (My guess is you find System.Out.println too long.) I'm tring to see how I can adapt the guidelines to accept this function (writefln) and I can't see any sensible rule I could add. Any idea? Alternatively, writefln could be an exception to the rules, but then the exception would need a better rationale than it shouldn't look like Java. I mean, if Phobos makes unjustified exceptions to its naming conventions here and there for no good other reason than it looks good, it breaks the concistency and makes function names less predictable and less readable. But it'd be easier to rename the functions to fit the convention: write - write writeln - writeLine writef- writeFormat writefln - writeLineFormat That way, if someone writes logging functions one day that takes formatted strings in the same way, he can reuse the convention: log logLine logFormat logLineFormat instead of log, logln, logf, and logfln. If you create a hash function, you can reuse the pattern too: hash hashLine hashFormat hashLineFormat instead of hash, hashln, hashf and hashfln. And it goes on. ... What does everyone thinks about all this? I think it's a good idea to have a good style guide; but rules only exist to make you think once before you break them. :) By thinking twice you should be able to come with a good justification; and if you can't then you should follow the rules. That's fine by me. -- Michel Fortin michel.for...@michelf.com http://michelf.com/
Re: Naming things in Phobos - std.algorithm and writefln
On 2009-08-05 03:49:34 -0400, Robert Fraser fraseroftheni...@gmail.com said: Michel Fortin wrote: As you know, I tried to write some guidelines[1] for naming things in D. Those guidelines looks well at first glance, but then you look at Phobos and you see that half of it use some arbitrary naming rules. Take writefln for instance: following my guidelines (as they are currently written) it should be renamed to something like writeFormattedLine. [1]: http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines I think naming guidelines aren't a bad thing, but they can be taken too far. We use an automated tool at work to check code and today I was forced to change the name of some classes because they ended in Queue or Dictionary and fix the spelling of Http because it thought it was Hungarian notation. That's indeed ridiculous. But that's not an example of guidelines gone too far, that's an example of a silly tool that's not even able to apply guidelines correctly. The guidelines I wrote are human-verifiable, not machine verifiable, and sometime require judgement. Exceptions to the guidelines are fine, as long as they have a good rationale supporting them. Even better than making exceptions to the guidelines is creating standardized patterns and adding it to the guideline. as I did with to functions (they don't start with a verb like the guideline says, but they are used as a convention for convertion functions). -- Michel Fortin michel.for...@michelf.com http://michelf.com/
Re: Naming things in Phobos - std.algorithm and writefln
Michel Fortin wrote: In std.algorithm, wouldn't it be clearer if splitter was called splitLazily or splitLazy? splitter is a noun, but as a function shouldn't it be a verb. makeSplitter or toSplitter perhaps? And what about the array function? Wouldn't it be clearer if it was toArray so we know we're preforming a convertion? As you know, I tried to write some guidelines[1] for naming things in D. Those guidelines looks well at first glance, but then you look at Phobos and you see that half of it use some arbitrary naming rules. Take writefln for instance: following my guidelines (as they are currently written) it should be renamed to something like writeFormattedLine. There should be an exception for functions which are analogous to C functions and have well established names in C. (eg, printf). Probably for famous functions in other languages, too. writeln() comes from Pascal, analogy with printf gives us writefln(). So that one's OK. I could take a look at std.algorithm and other modules in Phobos to list inconsistencies with the guidelines. From this we could make improvements both to the guideline document and the API. But before going too deep I think we should start with a few examples, such as those above, and see what to do with them. What does everyone thinks about all this? Yes, this is great. A review process would be very valuable. Please check the names in std.math. For the most part I have taken the names from the IEEE754-2008 standard, but please make suggestions. As we move towards finalizing D2.0, that module should be one of the first to have its interface frozen.
Re: Naming things in Phobos - std.algorithm and writefln
Michel Fortin Wrote: As you know, I tried to write some guidelines[1] for naming things in D. Those guidelines looks well at first glance, but then you look at Phobos and you see that half of it use some arbitrary naming rules. Take writefln for instance: following my guidelines (as they are currently written) it should be renamed to something like writeFormattedLine. [1]: http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines I think that's a problem with the guidelines. Anyone trying to turn D into Java should be shot. It's not clear what fln means, true... until you look up ANY output function with a f, ln or fln suffix and then it's obvious. Please, don't make unsupported accusations as an excuse to shoot people. Instead, you should say what you dislike about Java and explain why. (My guess is you find System.Out.println too long.) I'm tring to see how I can adapt the guidelines to accept this function (writefln) and I can't see any sensible rule I could add. Any idea? Alternatively, writefln could be an exception to the rules, but then the exception would need a better rationale than it shouldn't look like Java. I mean, if Phobos makes unjustified exceptions to its naming conventions here and there for no good other reason than it looks good, it breaks the concistency and makes function names less predictable and less readable. But it'd be easier to rename the functions to fit the convention: write - write writeln - writeLine writef- writeFormat writefln - writeLineFormat That way, if someone writes logging functions one day that takes formatted strings in the same way, he can reuse the convention: log logLine logFormat logLineFormat instead of log, logln, logf, and logfln. If you create a hash function, you can reuse the pattern too: hash hashLine hashFormat hashLineFormat instead of hash, hashln, hashf and hashfln. And it goes on. ... What does everyone thinks about all this? I think it's a good idea to have a good style guide; but rules only exist to make you think once before you break them. :) By thinking twice you should be able to come with a good justification; and if you can't then you should follow the rules. That's fine by me. I think the real problem underlying the wish to use writefln versus writeFormatLine (or anything like that), is that C programmers are in the habit of using very short names. But in my personal experience, most languages I use have a short formatted version of write..., probably because it is necessary many times. Although I agree that writefln, if adapted to the convention, should become writeFormatLine, I also understand the clumsiness of writing it. As far as I know, writefln is with us for a very long time. But it doesn't say that it should or should not be changed. I think that no one has been given any thought to it. I want to know: do we use writefln often, or is it just convenience, when writing out a something. I would imagine to have a formatter object that accepts a delegate which writes strings. I would as thus remove writefln, and just have the function write. The formatter object could be reponsible to actually use it, for example: Formatter.out(write, %s%s, Hello World, newline) The function write can still be used to emit directly, such as: write(Hello world\n) I think this is the real problem of writefln. Not the convention, but the approach.
Re: Naming things in Phobos - std.algorithm and writefln
Michel Fortin wrote: Alternatively, writefln could be an exception to the rules, but then the exception would need a better rationale than it shouldn't look like Java. I mean, if Phobos makes unjustified exceptions to its naming conventions here and there for no good other reason than it looks good, it breaks the concistency and makes function names less predictable and less readable. I agree that Phobos' names could use a good overhaul. That would make it easier for growing it too. Certain names could be kept short and intuitive although they don't fit common conventions. Andrei
Re: Naming things in Phobos - std.algorithm and writefln
Michel Fortin wrote: On 2009-08-05 03:29:11 -0400, Daniel Keep daniel.keep.li...@gmail.com said: makeSplitter is OK, but needlessly verbose. I think when you have a function whose only purpose is to construct something, or is strictly or conceptually pure, it's OK to use a noun for its name. Perhaps this rule should be added to the guideline then. But as it was said countless times in the all the threads about properties, many nouns are also verbs in English, and they can easily create confusion in this situation. Yes, there are lots of nouns that are also verbs but splitter isn't one of them. Just because they exist doesn't mean you can't ever use nouns without qualification. Calling directly the constructor of Splitter would be great, but alas you can't deduce struct template aruments from its constructor and have to rely on a separate function. My point was that there would be ZERO difference assuming we could; arguing that just because it's implemented using a function that it must be extra verbose is just silly. makeSplitter is the less consusing one in my opinion. It's more accurate but, as I said, needlessly verbose. splitter is a noun and it's hard to even deliberately think of ways to misinterpret it. I mean, we use sin(x) without problems although it could also have been written computeSineOf(x). Except, of course, then you'd have a hoard of angry numerical programmers knocking on your door with torches and pitchforks. Altenatively, we could rename splitter to split. After all, the documentation says Splits a range using another range or an element as a separator. If you want an array, you write split(...).toArray(), or perhaps better would be to have the resulting range implicitly-casted to an array when needed (but are implicit casts still in the pipe now that we have alias this?). No, naming it split implies that it's performing the split action on its arguments, which is *isn't*. Implying that it does *anything* in the function name is misleading since nothing actually takes place until *after* the function has returned. ... I think that's a problem with the guidelines. Anyone trying to turn D into Java should be shot. It's not clear what fln means, true... until you look up ANY output function with a f, ln or fln suffix and then it's obvious. Please, don't make unsupported accusations as an excuse to shoot people. Instead, you should say what you dislike about Java and explain why. (My guess is you find System.Out.println too long.) I was attempting to be jovial. [1] Java and, to a lesser extent, .NET have this serious problem where all of the names are needlessly long and verbose. This makes writing actual code tedious and annoying. No, I do not use an IDE and I shouldn't NEED autocomplete to be able to write code efficiently. Also, making code longer means less of it fits on a line, less on a page and most critically of all: less in your brain. Look at legalese: it's incredibly accurate but also almost impossible to read. I've found that it takes so long to read a sentence that by the time you finish, you've forgotten what it was about. Just because a name is unambiguous doesn't automatically make it good. writefln is a good name because the root indicates what it does it writes to something, the f comes from printf and ln is used in a few languages. What's more, even if you don't know what those suffixes mean initially, because they're used *consistently*, once you learn it you can apply it all over the place. And best of all: it's short to type. [2] I'm tring to see how I can adapt the guidelines to accept this function (writefln) and I can't see any sensible rule I could add. Any idea? Short suffixes are good when applied consistently across multiple symbols.? Alternatively, writefln could be an exception to the rules, but then the exception would need a better rationale than it shouldn't look like Java. I mean, if Phobos makes unjustified exceptions to its naming conventions here and there for no good other reason than it looks good, it breaks the concistency and makes function names less predictable and less readable. As I indicated above, it's descriptive, consistent and short; a great name. But it'd be easier to rename the functions to fit the convention: I find that supposition hard to accept. ... That way, if someone writes logging functions one day that takes formatted strings in the same way, he can reuse the convention: log logLine logFormat logLineFormat instead of log, logln, logf, and logfln. If you create a hash function, you can reuse the pattern too: hash hashLine hashFormat hashLineFormat instead of hash, hashln, hashf and hashfln. And it goes on. How is this an improvement? If we accept that people know what the f and ln suffixes mean (and given that they will be exposed to this in the course of writing a Hello, World! program), what
Re: Naming things in Phobos - std.algorithm and writefln
Michel Fortin wrote: I'm tring to see how I can adapt the guidelines to accept this function (writefln) and I can't see any sensible rule I could add. Any idea? Alternatively, writefln could be an exception to the rules, but then the exception would need a better rationale than it shouldn't look like Java. Um, how about writefln is AWESOME for a reason? :) But seriously, I use writefln ALL the time. I can't find the words to describe how much nicer it is than Tango's Stdout.formatln(blah) or Java's System.out.println(aargh). -Lars
Re: Naming things in Phobos - std.algorithm and writefln
Andrei Alexandrescu Wrote: Michel Fortin wrote: Alternatively, writefln could be an exception to the rules, but then the exception would need a better rationale than it shouldn't look like Java. I mean, if Phobos makes unjustified exceptions to its naming conventions here and there for no good other reason than it looks good, it breaks the concistency and makes function names less predictable and less readable. I agree that Phobos' names could use a good overhaul. That would make it easier for growing it too. Certain names could be kept short and intuitive although they don't fit common conventions. Andrei You could also use aliases to make everyone happy, thats what I do in my local phobos source, its just a bitch to upgrade to the newest dmd while keeping my own changes ;) One of the most annoying names I've had in phobos was the std.utf.encode/decode functions. When I would come across these in some code it wasnt descriptive enough as to what was being done. So I rewrote the std.utf module to use names such as toUTF8, toUTF16 and toUnicode, and made a generic toUTF template to call the proper one. Then aliased encode and decode to their corresponding toUTF calls to keep compatibility with the rest of phobos, works like a charm. I can mail you my version of std.utf if you want Andrei.
Re: Naming things in Phobos - std.algorithm and writefln
Jeremie Pelletier wrote: Andrei Alexandrescu Wrote: Michel Fortin wrote: Alternatively, writefln could be an exception to the rules, but then the exception would need a better rationale than it shouldn't look like Java. I mean, if Phobos makes unjustified exceptions to its naming conventions here and there for no good other reason than it looks good, it breaks the concistency and makes function names less predictable and less readable. I agree that Phobos' names could use a good overhaul. That would make it easier for growing it too. Certain names could be kept short and intuitive although they don't fit common conventions. Andrei You could also use aliases to make everyone happy, thats what I do in my local phobos source, its just a bitch to upgrade to the newest dmd while keeping my own changes ;) One of the most annoying names I've had in phobos was the std.utf.encode/decode functions. When I would come across these in some code it wasnt descriptive enough as to what was being done. So I rewrote the std.utf module to use names such as toUTF8, toUTF16 and toUnicode, and made a generic toUTF template to call the proper one. Then aliased encode and decode to their corresponding toUTF calls to keep compatibility with the rest of phobos, works like a charm. I can mail you my version of std.utf if you want Andrei. I'd be glad to look at it! Just give me time. Andrei
Re: Naming things in Phobos - std.algorithm and writefln
Wed, 05 Aug 2009 17:29:11 +1000, Daniel Keep wrote: Michel Fortin wrote: In std.algorithm, wouldn't it be clearer if splitter was called splitLazily or splitLazy? splitter is a noun, but as a function shouldn't it be a verb. makeSplitter or toSplitter perhaps? This is a specious argument. splitter's only purpose is to return an instance of a Splitter struct. You can't call it splitLazily or splitLazy because that implies that the function is doing work, when it really isn't. That's if you know how it works. But if you just use these functions, it's not even remotely obvious what the difference is, and the difference in naming is so subtle that many people will be doomed to forever confuse these functions, myself included. I confuse getopt and getopts shell functions in the same way. I simply can't remember which is which.
Re: Naming things in Phobos - std.algorithm and writefln
Sergey Gromov wrote: Wed, 05 Aug 2009 17:29:11 +1000, Daniel Keep wrote: Michel Fortin wrote: In std.algorithm, wouldn't it be clearer if splitter was called splitLazily or splitLazy? splitter is a noun, but as a function shouldn't it be a verb. makeSplitter or toSplitter perhaps? This is a specious argument. splitter's only purpose is to return an instance of a Splitter struct. You can't call it splitLazily or splitLazy because that implies that the function is doing work, when it really isn't. That's if you know how it works. But if you just use these functions, it's not even remotely obvious what the difference is, and the difference in naming is so subtle that many people will be doomed to forever confuse these functions, myself included. I confuse getopt and getopts shell functions in the same way. I simply can't remember which is which. Very true. If it weren't for backwards compatibility, I'd simply have split() do the lazy thing. Then array(split()) would do the eager thing. Andrei
Re: Naming things in Phobos - std.algorithm and writefln
On Wed, Aug 5, 2009 at 2:40 PM, Andrei Alexandrescuseewebsiteforem...@erdani.org wrote: Sergey Gromov wrote: Wed, 05 Aug 2009 17:29:11 +1000, Daniel Keep wrote: Michel Fortin wrote: In std.algorithm, wouldn't it be clearer if splitter was called splitLazily or splitLazy? splitter is a noun, but as a function shouldn't it be a verb. makeSplitter or toSplitter perhaps? This is a specious argument. splitter's only purpose is to return an instance of a Splitter struct. You can't call it splitLazily or splitLazy because that implies that the function is doing work, when it really isn't. That's if you know how it works. But if you just use these functions, it's not even remotely obvious what the difference is, and the difference in naming is so subtle that many people will be doomed to forever confuse these functions, myself included. I confuse getopt and getopts shell functions in the same way. I simply can't remember which is which. Very true. If it weren't for backwards compatibility, I'd simply have split() do the lazy thing. Then array(split()) would do the eager thing. Andrei Maybe introduce a convention like python and bearophile? foo for eager things and xfoo for lazy things is what they use. At least when you first see xfoo, you don't automatically assume you know what that x means, and go look it up if you don't know. --bb
Re: Naming things in Phobos - std.algorithm and writefln
On 2009-08-05 18:12:16 -0400, Bill Baxter wbax...@gmail.com said:
On Wed, Aug 5, 2009 at 2:40 PM, Andrei
Alexandrescuseewebsiteforem...@erdani.org wrote:
Sergey Gromov wrote:
Wed, 05 Aug 2009 17:29:11 +1000, Daniel Keep wrote:
Michel Fortin wrote:
In std.algorithm, wouldn't it be clearer if splitter was called
splitLazily or splitLazy? splitter is a noun, but as a function
shouldn't it be a verb. makeSplitter or toSplitter perhaps?
This is a specious argument.
splitter's only purpose is to return an instance of a Splitter struct.
You can't call it splitLazily or splitLazy because that implies tha
t
the function is doing work, when it really isn't.
That's if you know how it works.
But if you just use these functions, it's not even remotely obvious what
the difference is, and the difference in naming is so subtle that many
people will be doomed to forever confuse these functions, myself
included. I confuse getopt and getopts shell functions in the same wa
y.
I simply can't remember which is which.
Very true. If it weren't for backwards compatibility, I'd simply have
split() do the lazy thing. Then array(split()) would do the eager thing.
Andrei
Maybe introduce a convention like python and bearophile? foo for
eager things and xfoo for lazy things is what they use. At least
when you first see xfoo, you don't automatically assume you know what
that x means, and go look it up if you don't know.
One question to ask is which one should be the default. If lazy should
be the default then we want the lazy on to be called split and the
non-lazy one to be called eagerSplit or whatever other convention for
non-lazy. str.eagerSplit() would just be a shortcut for
str.split().toArray().
Also, with implicit casts we wouldn't even need to bother about having
a different names for lazy and non-lazy results, we could just do:
string[] parts = str.split();
and it would implicitly convert the lazy range to an array. Can this be
done with alias this? Would need to test.
struct Range(T)
{
T[] toArray();
alias toArray this;
... other range things here...
}
--
Michel Fortin
michel.for...@michelf.com
http://michelf.com/
Re: Naming things in Phobos - std.algorithm and writefln
On Wed, Aug 5, 2009 at 7:00 PM, Michel Fortinmichel.for...@michelf.com wrote:
Also, with implicit casts we wouldn't even need to bother about having a
different names for lazy and non-lazy results, we could just do:
string[] parts = str.split();
and it would implicitly convert the lazy range to an array. Can this be done
with alias this? Would need to test.
struct Range(T)
{
T[] toArray();
alias toArray this;
... other range things here...
}
Sadly it doesn't work. I was hopeful when I found this works:
struct X { int x; alias x this; }
auto x = X(5);
int y = x; // works!
but if you alias a method that returns int to 'this', that line fails.
Re: Naming things in Phobos - std.algorithm and writefln
On Wed, 05 Aug 2009 18:47:35 -0400, Michel Fortin michel.for...@michelf.com wrote: On 2009-08-05 17:40:34 -0400, Andrei Alexandrescu seewebsiteforem...@erdani.org said: Sergey Gromov wrote: Wed, 05 Aug 2009 17:29:11 +1000, Daniel Keep wrote: Michel Fortin wrote: In std.algorithm, wouldn't it be clearer if splitter was called splitLazily or splitLazy? splitter is a noun, but as a function shouldn't it be a verb. makeSplitter or toSplitter perhaps? This is a specious argument. splitter's only purpose is to return an instance of a Splitter struct. You can't call it splitLazily or splitLazy because that implies that the function is doing work, when it really isn't. That's if you know how it works. But if you just use these functions, it's not even remotely obvious what the difference is, and the difference in naming is so subtle that many people will be doomed to forever confuse these functions, myself included. I confuse getopt and getopts shell functions in the same way. I simply can't remember which is which. Very true. If it weren't for backwards compatibility, I'd simply have split() do the lazy thing. Then array(split()) would do the eager thing. But then I thought D2 was about making things better without worrying too much about backward compatibility. I find it dubious that we are ready to do a breaking language change about how properties work, but when it comes to replacing some standard library functions we can't because of backward compatibility. What is the criterion for an acceptable breaking changes? About 500 more posts ;) -Steve
Re: Naming things in Phobos - std.algorithm and writefln
Michel Fortin wrote: On 2009-08-05 17:40:34 -0400, Andrei Alexandrescu seewebsiteforem...@erdani.org said: Sergey Gromov wrote: Wed, 05 Aug 2009 17:29:11 +1000, Daniel Keep wrote: Michel Fortin wrote: In std.algorithm, wouldn't it be clearer if splitter was called splitLazily or splitLazy? splitter is a noun, but as a function shouldn't it be a verb. makeSplitter or toSplitter perhaps? This is a specious argument. splitter's only purpose is to return an instance of a Splitter struct. You can't call it splitLazily or splitLazy because that implies that the function is doing work, when it really isn't. That's if you know how it works. But if you just use these functions, it's not even remotely obvious what the difference is, and the difference in naming is so subtle that many people will be doomed to forever confuse these functions, myself included. I confuse getopt and getopts shell functions in the same way. I simply can't remember which is which. Very true. If it weren't for backwards compatibility, I'd simply have split() do the lazy thing. Then array(split()) would do the eager thing. But then I thought D2 was about making things better without worrying too much about backward compatibility. I find it dubious that we are ready to do a breaking language change about how properties work, but when it comes to replacing some standard library functions we can't because of backward compatibility. What is the criterion for an acceptable breaking changes? That's what I keep on telling Walter! That, and the fact that American cars suck! Andrei
Re: Naming things in Phobos - std.algorithm and writefln
On 2009-08-05 19:16:17 -0400, Jarrett Billingsley
jarrett.billings...@gmail.com said:
On Wed, Aug 5, 2009 at 7:00 PM, Michel Fortinmichel.for...@michelf.com wr
ote:
Also, with implicit casts we wouldn't even need to bother about having a
different names for lazy and non-lazy results, we could just do:
string[] parts = str.split();
and it would implicitly convert the lazy range to an array. Can this be d
one
with alias this? Would need to test.
struct Range(T)
{
T[] toArray();
alias toArray this;
... other range things here...
}
Sadly it doesn't work. I was hopeful when I found this works:
struct X { int x; alias x this; }
auto x = X(5);
int y = x; // works!
but if you alias a method that returns int to 'this', that line fails.
Looks pretty much like this bug. Put your vote on it.
http://d.puremagic.com/issues/show_bug.cgi?id=2814
There's also such an example in the original enhancement proposal for
alias this from Andrei.
http://d.puremagic.com/issues/show_bug.cgi?id=2631
--
Michel Fortin
michel.for...@michelf.com
http://michelf.com/
Re: Naming things in Phobos - std.algorithm and writefln
On 2009-08-05 20:08:43 -0400, Andrei Alexandrescu seewebsiteforem...@erdani.org said: But then I thought D2 was about making things better without worrying too much about backward compatibility. I find it dubious that we are ready to do a breaking language change about how properties work, but when it comes to replacing some standard library functions we can't because of backward compatibility. What is the criterion for an acceptable breaking changes? That's what I keep on telling Walter! That, and the fact that American cars suck! You mean it's Walter who don't want to break this kind of compatibilty? In any case, if Walter can fix alias this so that we can really do implicit casts, it will become possible to return a lazy range that implicitly convert to an array when needed. -- Michel Fortin michel.for...@michelf.com http://michelf.com/
Re: Naming things in Phobos - std.algorithm and writefln
Daniel Keep wrote: That way, if someone writes logging functions one day that takes formatted strings in the same way, he can reuse the convention: log logLine logFormat logLineFormat instead of log, logln, logf, and logfln. If you create a hash function, you can reuse the pattern too: hash hashLine hashFormat hashLineFormat instead of hash, hashln, hashf and hashfln. And it goes on. How is this an improvement? If we accept that people know what the f and ln suffixes mean (and given that they will be exposed to this in the course of writing a Hello, World! program), what benefit is gained from increasing the length and complexity of the identifiers? Saying you can re-use the convention is irrelevant because the exact same thing can be said of the shorter suffixes. The thing about one-letter abbreviations is that they mean different things in different contexts. An f might mean formatted in a writefln function, but it means file in an ifstream and floating point in the fenv module. In those cases (and in many more), there's no convention than can be reused. You just have to memorize stuff. Memorization was a perfectly acceptable solution back in the days of C, when standard libraries were small. But I think any modern standard library, with scores of modules and hundreds (or thousands) of functions, needs a better strategy. Coming from a Java background, I much prefer to give up terseness in favor of clarity. Though I recognize that verbosity has its own pitfalls, I think it's the lesser evil. --benji
Re: Naming things in Phobos - std.algorithm and writefln
Benji Smith wrote: ... The thing about one-letter abbreviations is that they mean different things in different contexts. An f might mean formatted in a writefln function, but it means file in an ifstream and floating point in the fenv module. I don't think this applies. Firstly, I was talking about suffixes, not abbreviations appearing in other parts of a name. Secondly, the convention is: an f suffix on an output method means formatting. That doesn't conflict with fenv at all since the f there isn't a suffix and env has nothing to do with output at all. Besides, even if you thought the f was formatter, you'd be quickly dissuaded when you looked in the docs and saw fenv.h is the standard header providing access to the floating point environment. The ambiguous case is ifstream which could be interpreted as input formatted stream if you were really trying. But here's the kicker: ifstream is a bad class name ANYWAY because it's all lowercase and highly ambiguous. A sane name for ifstream would be FileInput which drops the redundant stream, expands both the i and f to their full names and is only one character longer. Win! Finally, I don't think you can just toss context out the window completely and say 'but there's an f; it could mean anything!'. No, interpret it based on context and all will be well. If you have an output function on a file with an 'f' suffix, odds are it means format. If you have a logging function on a logging object with an 'f' suffix, odds are it means format. If you have an inverse square root function on a math object with an 'f' suffix, odds are it really doesn't mean format. Given we have overloading, my guess would be fast, and then I'd check the docs. In those cases (and in many more), there's no convention than can be reused. You just have to memorize stuff. Memorization was a perfectly acceptable solution back in the days of C, when standard libraries were small. But I think any modern standard library, with scores of modules and hundreds (or thousands) of functions, needs a better strategy. You can't not memorise stuff. You have to look up the docs if you don't remember what a function's arguments are or what its semantics are irrespective of the name. Coming from a Java background, I much prefer to give up terseness in favor of clarity. Though I recognize that verbosity has its own pitfalls, I think it's the lesser evil. --benji It's alright; enough electro-therapy will cure you of your Java tendencies. We CAN save you!
Naming things in Phobos - std.algorithm and writefln
In std.algorithm, wouldn't it be clearer if splitter was called splitLazily or splitLazy? splitter is a noun, but as a function shouldn't it be a verb. makeSplitter or toSplitter perhaps? And what about the array function? Wouldn't it be clearer if it was toArray so we know we're preforming a convertion? As you know, I tried to write some guidelines[1] for naming things in D. Those guidelines looks well at first glance, but then you look at Phobos and you see that half of it use some arbitrary naming rules. Take writefln for instance: following my guidelines (as they are currently written) it should be renamed to something like writeFormattedLine. [1]: http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines I don't necessarily want to change every function name, but if we want this document to make sense and Phobos to have some uniformity, both should be harmonized. Phobos should give the example and follow the guidelines and the guidelines should match Phobos, otherwise the guidelines have no weight for developers of other libraries and Phobos will make life harder to those who want to follow them. For names we don't want to follow the guidelines, there should be some documentation explaining what rule they disobey and why. I could take a look at std.algorithm and other modules in Phobos to list inconsistencies with the guidelines. From this we could make improvements both to the guideline document and the API. But before going too deep I think we should start with a few examples, such as those above, and see what to do with them. What does everyone thinks about all this? -- Michel Fortin michel.for...@michelf.com http://michelf.com/
Re: Naming things: Phobos Programming Guidelines Propsal
Michel Fortin wrote:
It's interesting how the property debate is moving towards expressing
semantics and how sometime the English language doesn't express things
clearly -- empty (state) vs. empty (action) comes to mind.
Now that the debate is moving towards how to name things, perhaps it is
time we establish a clear set of guidelines. Here's my attempt at it:
http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines
It obviously lacks a few things, and doesn't fit half of today's Phobos
very well. But I hope this document can bring some consistency to Phobos
and other D projects. Feel free to discuss and improve the document as
you see fit.
There's a paradox. :-P
You say a class' name should be a noun. And you say a class' name
shouldn't repeat it's base class name.
Say you have an Action class, very common in UI toolkits and things like
that. Now you have an action to connect two things. Two alternatives:
1. class Connect : Action {} // wrong, Connect not a noun
2. class ConnectAction : Action {} // wrong, repeats Action
3. ...?
4. The universe expolodes.
Re: Naming things: Phobos Programming Guidelines Propsal
On 2009-07-29 10:53:59 -0400, Ary Borenszweig a...@esperanto.org.ar said:
Michel Fortin wrote:
It's interesting how the property debate is moving towards expressing
semantics and how sometime the English language doesn't express things
clearly -- empty (state) vs. empty (action) comes to mind.
Now that the debate is moving towards how to name things, perhaps it is
time we establish a clear set of guidelines. Here's my attempt at it:
http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines
It obviously lacks a few things, and doesn't fit half of today's Phobos
very well. But I hope this document can bring some consistency to
Phobos and other D projects. Feel free to discuss and improve the
document as you see fit.
There's a paradox. :-P
You say a class' name should be a noun. And you say a class' name
shouldn't repeat it's base class name.
Say you have an Action class, very common in UI toolkits and things
like that. Now you have an action to connect two things. Two
alternatives:
1. class Connect : Action {} // wrong, Connect not a noun
2. class ConnectAction : Action {} // wrong, repeats Action
3. ...?
4. The universe expolodes.
I'd go with ConnectAction to make sure there's a noun. The rule
following the don't repeat the base class name one is aimed at
allowing this specific usage. It says:
It is fine to repeat the base type name in the derived type name if the
derived type is only a specialization having the same function:
class RemoteObject : Object { } // right
class TcpSocket : Socket { }// right
Obviously it doesn't seem too well worded. Any alternative suggestion?
--
Michel Fortin
michel.for...@michelf.com
http://michelf.com/
Re: Naming things: Phobos Programming Guidelines Propsal
On 2009-07-29 11:24:18 -0400, Ary Borenszweig a...@esperanto.org.ar said:
Michel Fortin wrote:
I'd go with ConnectAction to make sure there's a noun. The rule
following the don't repeat the base class name one is aimed at
allowing this specific usage. It says:
It is fine to repeat the base type name in the derived type name if the
derived type is only a specialization having the same function:
class RemoteObject : Object { } // right
class TcpSocket : Socket { }// right
Obviously it doesn't seem too well worded. Any alternative suggestion?
I like it like that. It's a good rule. :)
I added your ConnectAction example, this way there is an example with a
verb in front of a noun.
--
Michel Fortin
michel.for...@michelf.com
http://michelf.com/
Re: Naming things: Phobos Programming Guidelines Propsal
I did some formatting for the page, and linked to the Style Guide. You should note that by having a author field you are giving the impression that changes should go through you. Michel Fortin Wrote: It's interesting how the property debate is moving towards expressing semantics and how sometime the English language doesn't express things clearly -- empty (state) vs. empty (action) comes to mind. Now that the debate is moving towards how to name things, perhaps it is time we establish a clear set of guidelines. Here's my attempt at it: http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines It obviously lacks a few things, and doesn't fit half of today's Phobos very well. But I hope this document can bring some consistency to Phobos and other D projects. Feel free to discuss and improve the document as you see fit. -- Michel Fortin michel.for...@michelf.com http://michelf.com/
Re: Naming things: Phobos Programming Guidelines Propsal
On 2009-07-29 13:46:46 -0400, Jesse Phillips jessekphillip...@gmail.com said: I did some formatting for the page, and linked to the Style Guide. Good idea. I think eventually, if the guidelines actually get some attention, both documents should be merged. They're essentially two sides of the same coin. You should note that by having a author field you are giving the impression that changes should go through you. Ah, well. That's not my intent, otherwise I wouldn't have posted this on a wiki. Fixed. -- Michel Fortin michel.for...@michelf.com http://michelf.com/
Re: Naming things: Phobos Programming Guidelines Propsal
Chad J wrote:
Ary Borenszweig wrote:
1. class Connect : Action {} // wrong, Connect not a noun
2. class ConnectAction : Action {} // wrong, repeats Action
3. ...?
4. The universe expolodes.
Why would there be a Connect class?
class Connection : Action {}
Nevermind that might not actually make sense.
tada! English words can often be nounized.
Sorry for the noise.
Re: Naming things: Phobos Programming Guidelines Propsal
Ary Borenszweig wrote:
Michel Fortin wrote:
It's interesting how the property debate is moving towards expressing
semantics and how sometime the English language doesn't express things
clearly -- empty (state) vs. empty (action) comes to mind.
Now that the debate is moving towards how to name things, perhaps it
is time we establish a clear set of guidelines. Here's my attempt at it:
http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines
It obviously lacks a few things, and doesn't fit half of today's
Phobos very well. But I hope this document can bring some consistency
to Phobos and other D projects. Feel free to discuss and improve the
document as you see fit.
There's a paradox. :-P
You say a class' name should be a noun. And you say a class' name
shouldn't repeat it's base class name.
Say you have an Action class, very common in UI toolkits and things like
that. Now you have an action to connect two things. Two alternatives:
1. class Connect : Action {} // wrong, Connect not a noun
2. class ConnectAction : Action {} // wrong, repeats Action
3. ...?
4. The universe expolodes.
Why would there be a Connect class?
class Connection : Action {}
tada! English words can often be nounized.
