Thursday, September 12, 2019

Parameter order



https://softwareengineering.stackexchange.com/questions/101346/what-is-best-practice-on-ordering-parameters-in-a-function
 I don't over-think it, except for public API design.

Selection Funnel

  1. Semantics
  2. Importance / Relevance
  3. Frequency of Use
  4. I/O Concerns

1. Semantics First

Especially in OOP, pick parameters based on their semantical significance for the action or message. The signature of a well-named method with a well-named parameter should:
  • feel natural to call,
  • be self-descriptive in terms of intent and behavior.
(For these reasons, sometimes using custom types or aliases instead of primitives might increase the expressiveness of your signature.)

2. Then Importance

The most "significant" parameter comes first (or next...)

3. Then Frequency

The frequency matters as well, especially in a language where you don't have named parameters but can have default values on positional parameters. That implies that the order of the parameters doesn't vary, and that obviously you cannot set the N + 1 parameters if you want to force the default value of the Nth parameter (except if your language has a concept of a place-holder parameter).
The good news for you is that usually, frequency relates to importance, so that goes hand in hand with the previous point. And then it's probably up to you to craft your API for it to have the appropriate semantics.

4. Let's Not Forget I/O

if your method/function takes some input and produces an output, and the latter is not to be "returned" (via a return statement) or "thrown" (using an exception system), then you're left with the option to pass values back to the caller using your other parameters (or the input parameter). That relates to semantics, and in most cases it will make sense to have the first parameters define the output, and the last parameters receive the output.
Additionally, an other approach to have less parameters and maximise semantics would be to use a functional approach, or to define a Builder pattern, so you can clearly stack up your inputs, define your outputs, and retrieve them when need be.
  • If a language allows default values for parameters (such as C++, Sybase stored procedures), you obviously leave the optional parameters to be the last, and the less likely the parameter is to be specified with a value, the later in the list it should go.
  • Otherwise, order them in whatever logical grouping is most readable/maintainable.
    This may be a bit subjective - e.g. next/previous weight/height can be ordered next_weight,next_height, prev_weight, prev_height or next_weight, prev_weight, next_height, prev_height equally validly. Again, the 3 main considerations are readability/logicaleness for you, and ease of maintenance.
    As far as readability, you can order them by type, or by meaning.
    As far as "logicalness", you can order them by meaning (e.g. group all "next" together, or all heights together), OR by some order imposed elsewhere - for example, column order in a corresponding database table, or field order in a GUI (worse, as it's likely to change).
    As far as maintenance, if no obvious meaningful order crystallizes, alphanumeric order is the best since it allows VERY easy way to find a parameter by scanning and especially to decide where to insert a new parameter.

 group arguments of similar origin together

Saturday, September 7, 2019

Javadoc Best Practice



https://blog.codefx.org/java/new-javadoc-tags/
* @apiNote This method was added after the interface was released in
*          version 1.0. It is defined as a default method for compatibility
*          reasons. From version 2.0 on, the method will be abstract and
*          all implementations of this interface have to provide their own
*          implementation of the method.
* @implSpec The default implementation will consider each player a winner
*           and return them in an unspecified order.
* @implNote This implementation has linear runtime and does not filter out
*           null players.



https://stackoverflow.com/questions/11671989/best-practice-for-javadocs-interface-implementation-or-both?lq=1
If the implementing method doesn't provide its own Javadoc, there will still be a link to the interface method's docs. I never understood why Eclipse inserts /* (non-Javadoc) @see ... */ as the Javadocs will automatically reference the interface's docs.
The interface should have all the information about the contract, basically what the method does, the description of parameters, return values and so on.
Unless there's some extra information that isn't clear from the interface description (there rarely is), the implementation documentation should then simply link to the interface method

https://engdoc.corp.google.com/eng/doc/devguide/java/style/index.md?cl=head#s7-javadoc
Each paragraph except the first has <p> immediately before the first word, with no space after it
new paragraphs both be introduced with a blank line and be prefixed with <p>.

https://blog.joda.org/2012/11/javadoc-coding-standards.html
Do not use '**/' at the end of the Javadoc.
Use simple HTML tags, not valid XHTML

Define a punchy first sentence
The first sentence, typically ended by a dot, is used in the next-level higher Javadoc. As such, it has the responsibility of summing up the method or class to readers scanning the class or package. To achieve this, the first sentence should be clear and punchy, and generally short.
While not required, it is recommended that the first sentence is a paragraph to itself. This helps retain the punchiness for readers of the source code.
It is recommended to use the third person form at the start. For example, "Gets the foo", "Sets the "bar" or "Consumes the baz". Avoid the second person form, such as "Get the foo".

Use "this" to refer to an instance of the class
When referring to an instance of the class being documented, use "this" to reference it. For example, "Returns a copy of this foo with the bar value updated".
Aim for short single line sentences

Use @link and @code wisely
Many Javadoc descriptions reference other methods and classes. This can be achieved most effectively using the @link and @code features.
The @link feature creates a visible hyperlink in generated Javadoc to the target. The @link target is one of the following forms:
  /**
   * First paragraph.
   * <p>
   * Link to a class named 'Foo': {@link Foo}.
   * Link to a method 'bar' on a class named 'Foo': {@link Foo#bar}.
   * Link to a method 'baz' on this class: {@link #baz}.
   * Link specifying text of the hyperlink after a space: {@link Foo the Foo class}.
   * Link to a method handling method overload {@link Foo#bar(String,int)}.
   */
  public ...
The @code feature provides a section of fixed-width font, ideal for references to methods and class names. While @link references are checked by the Javadoc compiler, @code references are not.
Only use @link on the first reference to a specific class or method. Use @code for subsequent references. This avoids excessive hyperlinks cluttering up the Javadoc.

Define null-handling for all parameters and return types
Whether a method accepts null on input, or can return null is critical information for building large systems. All non-primitive methods should define their null-tolerance in the @param or @return. Some standard forms expressing this should be used wherever possible:
  • "not null" means that null is not accepted and passing in null will probably throw an exception , typically NullPointerException
  • "may be null" means that null may be passed in. In general the behaviour of the passed in null should be defined
  • "null treated as xxx" means that a null input is equivalent to the specified value
  • "null returns xxx" means that a null input always returns the specified value
When defined in this way, there should not be an @throws for NullPointerException.
  /**
   * Javadoc text.
   * 
   * @param foo  the foo parameter, not null
   * @param bar  the bar parameter, null returns null
   * @return the baz content, null if not processed
   */
  public String process(String foo, String bar) {...}





Sunday, September 1, 2019

How to Reduce Data Usage




3. See which apps are using the most data

Curious to know which apps are consuming the most data? Go to Settings > Cellularand you can see how much data you've used in the current billing period and below that you'll see a list of your apps. 

4. Disable Wi-Fi Assist

Wi-Fi Assist is a great feature where your iPhone hands off a weak Wi-Fi signal to your cellular network to prevent pages from loading slowly (or not at all) as it clings to the last remnants of a Wi-Fi signal. If you sit on the edge of a Wi-Fi network at work, say, then your cellular network may be assisting more than you'd like and running up data charges.
To disable Wi-Fi Assist, go to Settings > Cellular and scroll all the way to the bottom to turn off Wi-Fi Assist.

5. Download music, don't stream

For Apple Music, go to Settings > Music. In the Streaming & Downloads section, you'll see two settings if the first is enabled. The first, Use Cellular Data, lets you disable streaming via a cellular connection entirely. If that's too drastic a measure for you, then you can leave that setting enabled and turn off High Quality on Cellular to stream songs at a lower bitrate when you aren't on Wi-Fi.
For the Podcasts app, go to Settings > Podcasts and turn off Cellular Data. You can also enable Only Download on Wi-Fi to prevent podcast downloads from adding to your data usage.

7. Use Safari's Reading List

You can queue up articles while you're using Wi-Fi to read later when you're on a cellular connection or out of range completely. When you add a page to Safari's Reading List, Safari downloads it for offline viewing. To add an article to the Reading List, tap the Share button at the center of the bottom navigation bar and then tap Add to Reading List. If you use iCloud, then it will share your Reading List with your other iOS devices, but you can stop it from sharing via a cellular connection by going to Settings > Safari and scrolling down to the bottom and toggling off Use Cellular Datafor the Reading List feature.





https://www.telegraph.co.uk/technology/2016/04/10/how-to-reduce-your-android-or-iphone-data-usage/

4. Disable background app refresh
This is one for iPhone users only, but turning off background app refresh by entering Settings > General > and either turning off refresh altogether or going through and selecting individual apps will not only help to cut down on your data usage, it has the added bonus of helping to preserve your battery life. Win win!

Labels

Review (572) System Design (334) System Design - Review (198) Java (189) Coding (75) Interview-System Design (65) Interview (63) Book Notes (59) Coding - Review (59) to-do (45) Linux (43) Knowledge (39) Interview-Java (35) Knowledge - Review (32) Database (31) Design Patterns (31) Big Data (29) Product Architecture (28) MultiThread (27) Soft Skills (27) Concurrency (26) Cracking Code Interview (26) Miscs (25) Distributed (24) OOD Design (24) Google (23) Career (22) Interview - Review (21) Java - Code (21) Operating System (21) Interview Q&A (20) System Design - Practice (20) Tips (19) Algorithm (17) Company - Facebook (17) Security (17) How to Ace Interview (16) Brain Teaser (14) Linux - Shell (14) Redis (14) Testing (14) Tools (14) Code Quality (13) Search (13) Spark (13) Spring (13) Company - LinkedIn (12) How to (12) Interview-Database (12) Interview-Operating System (12) Solr (12) Architecture Principles (11) Resource (10) Amazon (9) Cache (9) Git (9) Interview - MultiThread (9) Scalability (9) Trouble Shooting (9) Web Dev (9) Architecture Model (8) Better Programmer (8) Cassandra (8) Company - Uber (8) Java67 (8) Math (8) OO Design principles (8) SOLID (8) Design (7) Interview Corner (7) JVM (7) Java Basics (7) Kafka (7) Mac (7) Machine Learning (7) NoSQL (7) C++ (6) Chrome (6) File System (6) Highscalability (6) How to Better (6) Network (6) Restful (6) CareerCup (5) Code Review (5) Hash (5) How to Interview (5) JDK Source Code (5) JavaScript (5) Leetcode (5) Must Known (5) Python (5)

Popular Posts