reverendsteveii, 1 year ago (edited 1 year ago)

`//Get CustomerInfo from CustomerRepository by Customer ID or else throw an CustomerNotFoundException

public CustomerInfo getById(String customerId) {

<span style="color:#323232;">return customerRepository.getById(customerId).orElseThrow(new CustomerNotFoundException());
</span>

}`

This is the kind of pointless comment I see in my codebase all the time. Best I can tell, a couple of my coworkers like to plan out their code using comments, then backfill in the actual executable code. That’s fine, but they leave the comments in when they add no value.

` public static LocalDate parseEndDateFromString(String dateString) {

<span style="color:#323232;">    try {
</span><span style="color:#323232;">
</span><span style="color:#323232;">        String[] split = dateString.split("-");
</span><span style="color:#323232;">
</span><span style="color:#323232;">        //In order to get the last day of the desired month, we go to the first day of the next month, account for rollover, then subtract one day
</span><span style="color:#323232;">
</span><span style="color:#323232;">        int month = Integer.parseInt(split[0]) == 12 ? 1 : Integer.parseInt(split[0]) + 1;
</span><span style="color:#323232;">
</span><span style="color:#323232;">        return LocalDate.of(Integer.parseInt(split[1]), month, 1).minusDays(1);
</span><span style="color:#323232;">
</span><span style="color:#323232;">    } catch (Exception e) {
</span><span style="color:#323232;">
</span><span style="color:#323232;">        throw new RuntimeException("Invalid date format - must be MM-YYYY");
</span><span style="color:#323232;">
</span><span style="color:#323232;">    }
</span><span style="color:#323232;">
</span><span style="color:#323232;">}`
</span>

Stuff like this, otoh, is where comments are useful. The required format is obvious from the error message, the param and return from the method signature, the only part that requires a comment is the fiddly logic of accounting for the edge case where month == 12 and the rationale behind how we determine the last day of the month. As a rule, comments are for why something is being done, if it’s not obvious, and for magic numbers. Code should tell you what code does.

edit: can anyone spot the bug that I introduced with that parseEndDateFromString() method?