[dart-misc] Best practice for documenting non-obvious parameter call sites

['Benjamin Smith' via Dart Misc]

Hello,

I am relatively new to Dart, and was wondering what the recommended
practice is for documenting non-obvious call sites.

For example, in Java I would use an inline comment to write:

someObject.someMethod(meaningfulParm1, meaningfulParm2,
/*lessObviousParm=*/5);

In Dart, I don't see a recommendation in the style guide, except not to use
/* */ block comments.
https://www.dartlang.org/guides/language/effective-dart/documentation#dont-use-block-comments-for-documentation

Named parameters look interesting, but doesn't feel like the right fit.

Thanks!

Ben

[Randal L. Schwartz]

Benjamin> For example, in Java I would use an inline comment to write:

Benjamin> someObject.someMethod(meaningfulParm1, meaningfulParm2,
Benjamin> /*lessObviousParm=*/5);

Benjamin> In Dart, I don't see a recommendation in the style guide, except not to use
Benjamin> /* */ block comments.
Benjamin> https://www.dartlang.org/guides/language/effective-dart/documentation#dont-use-block-comments-for-documentation

You might have missed this:

https://www.dartlang.org/guides/language/effective-dart/documentation#do-use-prose-to-explain-parameters-return-values-and-exceptions

/// Defines a flag.
///
/// Throws an [ArgumentError] if there is already an option named [name] or
/// there is already an option using abbreviation [abbr]. Returns the new flag.
Flag addFlag(String name, String abbr) => ...
--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - [phone]
<***@stonehenge.com> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/Dart consulting, Technical writing, Comedy, etc. etc.
Still trying to think of something clever for the fourth line of this .sig

['Samuel Rawlins' via Dart Misc]

Hmm yeah, Effective Dart doesn't say anything about when to use named or
positional parameters, but the best practices I've seen are to at least use
named parameters for integer or boolean parameters (where literals are
often passed as the arguments), when they're sort of secondary purposed, or
optional. This way, you can avoid the /* */ inline comment.

For example, I think if String.replaceFirst was re-written today, it would
not use its current parameters:

String replaceFirst (Pattern from, String to, [int startIndex = 0])

where the user writes "/a/b/c".replaceFirst('/', '_', 2) and no one knows
what 2 means. It would instead used a named parameter:

String replaceFirst (Pattern from, String to, {int startIndex = 0})

So that the user writes "a/b/c".replaceFirst('/', '_', startIndex: 2). Much
nicer!

Post by Randal L. Schwartz
Benjamin> someObject.someMethod(meaningfulParm1, meaningfulParm2,
Benjamin> /*lessObviousParm=*/5);
Benjamin> In Dart, I don't see a recommendation in the style guide, except not to use
Benjamin> /* */ block comments.
Benjamin>
https://www.dartlang.org/guides/language/effective-dart/documentation#dont-use-block-comments-for-documentation
https://www.dartlang.org/guides/language/effective-dart/documentation#do-use-prose-to-explain-parameters-return-values-and-exceptions
/// Defines a flag.
///
/// Throws an [ArgumentError] if there is already an option named [name] or
/// there is already an option using abbreviation [abbr]. Returns the new flag.
Flag addFlag(String name, String abbr) => ...
--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - [phone]
Perl/Unix/Dart consulting, Technical writing, Comedy, etc. etc.
Still trying to think of something clever for the fourth line of this .sig
--
For more ways to connect visit https://www.dartlang.org/community
---
You received this message because you are subscribed to the Google Groups
"Dart Misc" group.
To unsubscribe from this group and stop receiving emails from it, send an
To view this discussion on the web visit
https://groups.google.com/a/dartlang.org/d/msgid/misc/86efcuyk0x.fsf%40red.stonehenge.com
.

['Benjamin Smith' via Dart Misc]

That makes sense.

So the rule of thumb I will now follow:
- where the parameters are optional / secondary, use named parameters for
documentation
- else, use inline comment

Post by 'Samuel Rawlins' via Dart Misc
Hmm yeah, Effective Dart doesn't say anything about when to use named or
positional parameters, but the best practices I've seen are to at least use
named parameters for integer or boolean parameters (where literals are
often passed as the arguments), when they're sort of secondary purposed, or
optional. This way, you can avoid the /* */ inline comment.
For example, I think if String.replaceFirst was re-written today, it would
String replaceFirst (Pattern from, String to, [int startIndex = 0])
where the user writes "/a/b/c".replaceFirst('/', '_', 2) and no one knows
String replaceFirst (Pattern from, String to, {int startIndex = 0})
So that the user writes "a/b/c".replaceFirst('/', '_', startIndex: 2).
Much nicer!

Post by Randal L. Schwartz
Benjamin> someObject.someMethod(meaningfulParm1, meaningfulParm2,
Benjamin> /*lessObviousParm=*/5);
Benjamin> In Dart, I don't see a recommendation in the style guide, except not to use
Benjamin> /* */ block comments.
Benjamin>
https://www.dartlang.org/guides/language/effective-dart/documentation#dont-use-block-comments-for-documentation
https://www.dartlang.org/guides/language/effective-dart/documentation#do-use-prose-to-explain-parameters-return-values-and-exceptions
/// Defines a flag.
///
/// Throws an [ArgumentError] if there is already an option named [name] or
/// there is already an option using abbreviation [abbr]. Returns the new flag.
Flag addFlag(String name, String abbr) => ...
--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - [phone]
http://www.stonehenge.com/merlyn/>
Perl/Unix/Dart consulting, Technical writing, Comedy, etc. etc.
Still trying to think of something clever for the fourth line of this .sig
--
For more ways to connect visit https://www.dartlang.org/community
---
You received this message because you are subscribed to the Google Groups
"Dart Misc" group.
To unsubscribe from this group and stop receiving emails from it, send an
To view this discussion on the web visit
https://groups.google.com/a/dartlang.org/d/msgid/misc/86efcuyk0x.fsf%40red.stonehenge.com
.