Programmers

• Learning Architecture via Prompts
• Android Development
• AI-assisted programming
• Why Has GitHub Copilot Become Dumber?
• The AI Assistant Is Way Smarter Than Me
• Network
• A Few Ways to Safely Use Public IPv6
• Using Common DDNS Subdomains May Cause China Telecom Broadband Service Degradation
• Compliance Discussion of Reverse Proxy in Home Networks
• Some Characteristics of China Telecom IPv6
• Why we should not think of UDP in terms of TCP
• Troubleshooting Linux Network Issues
• How to Improve Network Experience with a Self-Hosted DNS Service
• Bypassing ChatGPT VPN Detection
• Chat
• Which Languages Are Best for Multilingual Projects
• Third-party Library Pitfalls
• Design Specification Template
• Command Line Syntax Conventions
• Meanings of brackets in man pages
• Huawei C++ Coding Standards
• linux
• linux tour
• Troubleshooting
• windows
• Windows SSH Remote Login
• Understanding Windows Networking_WFP
• Understanding Windows Event Tracing (ETW)
• wireguard configuration
• Windows Blocking Network Traffic Capture
• Windows Firewall Management – netsh
• Windows Resources
• Windows Guide
• window-message
• Win-to-go
• environment
• Windows Subsystem Linux(WSL)
• WSL Mirrored Network Mode Configuration Guide
• wsl
• Virtual Memory Disk Setup
• vs-remote-debug
• How Many Principles of Design Patterns Are There?
• Cross-Platform Content Publishing Tool — A Review of "蚁小二"
• Jianshu Writing Experience

Learning Architecture via Prompts

• [Android Development]

Android Development

Preface: You might find this prompt somewhat abstract at first, but a little patience goes a long way—knowledge must first be memorized, then understood. A few exceptional minds grasp concepts instantly without practice, but for most of us, hands-on experience is essential. Through concrete implementation we generalize ideas, turning knowledge into second nature. Try committing these prompts to memory for now; they can guide everyday work, where you’ll gradually absorb their distilled wisdom. Feel free to share any thoughts you have.

Cursor Rule

// Android Jetpack Compose .cursorrules

// Flexibility Notice

// Note: This is a recommended project structure—stay flexible and adapt to the existing project layout.
// If the project follows a different organisation style, do not force these structural patterns.
// While applying Jetpack Compose best practices, prioritise maintaining harmony with the current architecture.

// Project Architecture & Best Practices

const androidJetpackComposeBestPractices = [
"Adapt to the existing architecture while upholding clean code principles",
"Follow Material Design 3 guidelines and components",
"Implement clean architecture with domain, data, and presentation layers",
"Use Kotlin coroutines and Flow for asynchronous operations",
"Use Hilt for dependency injection",
"Adhere to unidirectional data flow with ViewModel and UI State",
"Use Compose Navigation for screens management",
"Implement proper state hoisting and composition",
];

// Folder Structure

// Note: This is a reference structure—adapt it to your project’s existing organisation

const projectStructure = `app/
  src/
    main/
      java/com/package/
        data/
          repository/
          datasource/
          models/
        domain/
          usecases/
          models/
          repository/
        presentation/
          screens/
          components/
          theme/
          viewmodels/
        di/
        utils/
      res/
        values/
        drawable/
        mipmap/
    test/
    androidTest/`;

// Compose UI Guidelines

const composeGuidelines = `

1. Use remember and derivedStateOf appropriately
2. Implement proper recomposition optimisation
3. Apply the correct order of Compose modifiers
4. Follow naming conventions for composable functions
5. Implement proper preview annotations
6. Use MutableState for correct state management
7. Implement proper error handling and loading states
8. Leverage MaterialTheme for proper theming
9. Follow accessibility guidelines
10. Apply proper animation patterns
    `;

// Testing Guidelines

const testingGuidelines = `

1. Write unit tests for ViewModels and UseCases
2. Implement UI tests using the Compose testing framework
3. Use fake repositories for testing
4. Achieve adequate test coverage
5. Use proper test coroutine dispatchers
   `;

// Performance Guidelines

const performanceGuidelines = `

1. Minimise recompositions with proper keys
2. Use LazyColumn and LazyRow for efficient lazy loading
3. Implement efficient image loading
4. Prevent unnecessary updates with proper state management
5. Follow correct lifecycle awareness
6. Implement proper memory management
7. Use adequate background processing
   `;

References

• https://github.com/Project-Translation/awesome-cursorrules

AI-assisted programming

Embrace change.

Why Has GitHub Copilot Become Dumber?

The AI Assistant Is Way Smarter Than Me

For a middle-aged man who has been coding for ten years, once went abroad for a gilded stint, and still cares about saving face, admitting that AI is better than me is downright embarrassing.

The total monthly cost of all the AI tools I use doesn’t exceed 200 RMB, yet my boss pays me far more than that.

I fully expect earfuls of ridicule:

“That’s only you.”

“That’s what junior devs say.”

“It only handles the easy stuff.”

“It can’t do real engineering.”

“Its hallucinations are severe.”

“It’s not fit for production.”

My experience with AI tools has been robust enough to let me shrug off such mockery. This article won’t promote any specific tool; its main purpose is to create an echo in your thoughts, since I learn so much from each comment thread.

I was among the first users of GitHub Copilot; I started in the beta and, once it ended, renewed for a year without hesitation—and I’m still using it today. I no longer get excited when I solve a thorny problem on my own, nor do I take pride in “elegant code.” The only thing that thrills me now is when the AI accurately understands what I am trying to express, when my AI assistant fulfills my request—and exceeds my expectations.

Of the experience I accumulated over the past decade, what turns out to be most useful with AI tools is:

• Logic
• Design patterns
• Regular expressions
• Markdown
• Mermaid
• Code style
• Data structures and algorithms

More specifically:

• A major premise, a minor premise, and a suitable relation between them.
• Create dependencies cautiously and strictly prevent circular ones.
• Do not add relations unless necessary; do not broaden the scope of relations unless necessary.
• Strictly control the size of logic blocks.
• Use regex-based searches and, following naming conventions, generate code that lends itself to such searches.
• Generate Mermaid diagrams, review and fine-tune them, then use Mermaid diagrams to guide code generation.
• Use the names of data structures and algorithms to steer code generation.

I have spent a lot of time contributing to various open-source projects—some in familiar domains, others not. It’s experience that lets me ramp up quickly. You’ll notice that great projects all look alike, while lousy projects are lousy in their own distinct ways.

If my memory gradually deteriorates and I start forgetting all the knowledge I once accumulated, yet still have to keep programming to put food on the table, and if I could write only the briefest reminder to myself on a sticky note, I would jot: Google "How-To-Ask-Questions"

Are humans smarter than AI? Or are only some humans smarter than some AI?

I have to be honest: puffing up my own ego brings no real benefit. As the title says, this article tears off the façade and exposes what I truly feel inside—that AI is better than me, far better. Whenever doubts about AI creep in, I’ll remind myself:

Is AI dumber than humans? Or are only some humans dumber than some AI? Maybe I need to ask the question differently?

Network

• Network

Network

• Bypass firewall
  • [wireguard对抗运营商]
• Network troubleshooting
  • [linux网络问题定位]
  • [windows网络问题定位]

A Few Ways to Safely Use Public IPv6

Some people need to “go home” via public IPv6. Unlike Tailscale/Zerotier et al., which rely on NAT traversal to create direct tunnels, native IPv6 offers a straight-through connection. Cellular networks almost always hand out global IPv6 addresses, so “going home” is extremely convenient.

I previously posted Using Common DDNS Sub-domains on Home Broadband May Downgrade Telecom Service describing a pitfall with IPv6: domains get crawled. Exposing your domain is basically the same as exposing your IPv6 address. Once scanners find open services and inbound sessions pile up, the ISP may silently throttle or downgrade your line.

That thread mentioned domain scanning but not cyberspace scanning—which ignores whatever breadcrumbs you leave and just brute-forces entire address blocks. This is much harder to defend against.

Cyberspace scanning usually includes the following steps:

• Host-alive detection using ARP, ICMP, or TCP to list responsive IPs.
• Port / service discovery to enumerate open ports and identify service names, versions, and OS signatures.
• Operating-system fingerprinting by analyzing packet replies.
• Traffic collection to spot anomalies or attack patterns.
• Alias resolution mapping multiple IPs to the same router.
• DNS recon reverse-resolving IPs to domain names.

Below are a few methods to stay off those scanners:

1. Have your internal DNS server never return AAAA records.
2. Allow internal services to be reached only via domain names, never by raw IP.
3. Use a private DNS service such as AdGuardPrivate.

Prevent AAAA Records on the Internal DNS

When you browse the web, every outbound connection can leak your source IPv6. If a firewall isn’t in place, that address enters the scanners’ high-priority IP pools.

Even scanning only the last 16 bits of a /56 prefix becomes a smaller task once the prefix is leaked.

After years of IPv6 use, I have seen no practical difference between IPv6 and IPv4 for day-to-day browsing. So we can sacrifice IPv6 for outbound traffic and reserve it solely for “go home” access.

How to block AAAA records

Configure your internal DNS resolver to drop all AAAA answers.

Most home setups run AdGuard Home—see the screenshot:

Once applied, local devices reach the outside world over IPv4 only.

Never Expose Services by IP

Exposing a service on a naked port makes discovery trivial. When you start a service, avoid binding to 0.0.0.0 and ::; almost every tutorial defaults to 127.0.0.1 plus ::1 for good reason—listening on public addresses is risky.

Reverse-proxy only by domain name

nginx example

Set server_name to an actual hostname instead of _ or an IP.

server {
    listen 80;
    server_name yourdomain.com; # replace with your real domain

    # 403 for anything not the correct hostname
    if ($host != 'yourdomain.com') {
        return 403;
    }

    location / {
        root /path/to/your/web/root;
        index index.html index.htm;
    }

    # additional config...
}

IIS example

Remember to specify the exact hostname—never leave the host field blank.

Use a private DNS service

Create spoofed hostnames that resolve only inside your own DNS.

Benefits:

• Hostnames can be anything—no need to buy a public domain.
• If a fake hostname leaks, the attacker still has to point their DNS resolver at your private server.
• Scanning the IP alone is useless: one must also (a) know the fake name, (b) set their resolver to your DNS, (c) include that name in each request’s Host header. All steps have to succeed.

sequenceDiagram
  participant Scanner as Scanner
  participant DNS as Private DNS
  participant Service as Internal Service

  Scanner->>DNS: 1. Find private DNS address
  Scanner->>DNS: 2. Query fake hostname
  DNS-->>Scanner: 3. Return internal IP
  Scanner->>Service: 4. Construct Host header
  Note right of Service: Denied if Host ≠ fake hostname
  alt Correct Host
    Service-->>Scanner: 5a. Response
  else Wrong Host
    Service-->>Scanner: 5b. 403
  end

This significantly increases the scanning cost.

You can deploy AdGuardPrivate (almost a labeled AdGuard Home) or Tencent’s dnspod purely for custom records. Functionality differs, so evaluate accordingly.

Summary

1. Prevent the internal DNS from returning AAAA records

   • Pre-reqs
     • Public IPv6 prefix
     • Internal DNS resolver
   • Steps
     • Drop AAAA answers

2. Reach internal services only via domain names

   • Pre-reqs
     • You own a domain
     • Registrar supports DDNS
     • Local reverse proxy already running
   • Steps
     • Enable DDNS task
     • Host-based access only

3. Spin up a private DNS

   • Pre-reqs
     • Private DNS service with custom records and DDNS
   • Steps
     • Enable DDNS task
     • Map fake hostnames to internal services

Finally:

• Tailscale/Zerotier that successfully punch through are still the simplest and safest way to go home.
• Don’t hop on random Wi-Fi—you’ll give everything away in one shot. Grab a big-data SIM and keep your faith with the carrier for now. (Cheap high-traffic SIM? DM me. Not really.)

Using Common DDNS Subdomains May Cause China Telecom Broadband Service Degradation

I have been troubleshooting IPv6 disconnections and hole-punching failures for over three months. I’ve finally identified the root cause; here’s the story.

My First Post Asking for Help—IPv6 Disconnections

IPv6 had been working perfectly. Without touching any settings, and even though every device had its own IPv6, it suddenly lost IPv6 connectivity entirely.

curl 6.ipw.cn returned nothing, and both ping6 and traceroute6 2400:3200::1 failed.

My ONT was bridged to the router, and I could still obtain the router’s own IPv6—one that could still reach the IPv6 Internet.

I received a /56 prefix, and all downstream devices received addresses within 240e:36f:15c3:3200::/56, yet none could reach any IPv6 site.

I suspected the ISP had no route for 240e:36f:15c3:3200::, but I couldn’t prove it.

Someone suggested excessive PCDN upload traffic was the culprit, but upload volume was minimal and PCDN wasn’t enabled.

Another possibility was that using Cloudflare and Aliyun ESA reverse proxies had caused it.

My Second Post—Finding a Direct Cause

I confirmed that at least some regions of China Telecom will downswitch service when they see many inbound IPv6 HTTP/HTTPS connections, manifesting as:

• Fake IPv6: You still get a /56, every device keeps its IPv6, but traceroute lacks a route, so IPv6 is de-facto unusable.
• Fake hole- punch: Tailscale reports its connection is direct, yet latency is extreme and speed is terrible.

Every time I disabled Cloudflare/Aliyun ESA proxying and rebooted the router a few times, both real IPv6 connectivity and true direct Tailscale worked again.

Still Disconnects After Disabling Reverse Proxy

Even with proxy/CDN disabled—complete direct origin access—I still had occasional outages lasting hours.

Perhaps my domain had leaked, or bots were scanning popular subdomains with a steady HTTP attack.

When I disabled DNS resolution for the DDNS hostname outright, IPv6 came back after a while, and Tailscale hole-punching was again direct and stable.

Since then those disconnections never returned.

My Final Recommendation

Avoid using commonplace DDNS subdomains, such as:

• home.example.com
• nas.example.com
• router.example.com
• ddns.example.com
• cloud.example.com
• dev.example.com
• test.example.com
• webdav.example.com

I had used several of these; it seems they are continuously scanned by bots. The resulting flood of requests triggered China Telecom’s degradation policy, making my IPv6 unusable and blocking hole-punching.

As you already know, hiding your IP matters in network security; the same goes for protecting the domain you use for DDNS—that domain exposes your IP as well.

If you still need public services, you have two practical choices:

1. Proxy/Front-end relay—traffic hits a VPS first, then your home server. Latency and bandwidth suffer because traffic takes a detour.
2. DDNS direct—everything connects straight to you. Performance is much better; this is what I recommend. For personal use the number of connections rarely hits the limit, but once the domain becomes public the bots will ramp it up quickly.

Proxy Relay (Reverse Proxy)

Cloudflare Tunnel

Use Cloudflare’s Tunnel so you won’t see the dozens or hundreds of IPs typical of ordinary reverse proxies.

Tailscale or ZeroTier

Build your own VPN, put a VPS in front, and reach your LAN services through the VPN. This avoids excessive simultaneous connections.

DDNS Direct Scheme

Public DNS

Generate a random string—like a GUID—and use it as your DDNS hostname. It’s impossible to remember, but for personal use that’s acceptable. Judge for yourself.

Private DNS

Run your own DNS service, e.g.:

• AdguardPrivate
• dot.pub

Configure it to serve your DDNS records; only people who can query your private DNS will resolve the custom IP.

In this model you can use common DDNS names, but take care never to expose the address of your private DNS server.

Afterthought

Rumor has it that naming a subdomain speedtest might provide a mysterious boost.

Compliance Discussion of Reverse Proxy in Home Networks

Background

About 90 days ago, I encountered an IPv6 connectivity issue with China Telecom Hubei. After long-term observation and analysis, here are the findings.

Problem Analysis

Two initial suspected causes:

1. PCDN usage detection

   • No active use of PCDN
   • Only a small amount of BitTorrent downloads
   • Upload throttling has been applied, yet the problem persists

2. Home server acting as blog origin

   • Uses Cloudflare origin rules specifying a port
   • May be deemed “commercial behavior” by the ISP

After three months of validation, the issue is more likely triggered by exposing HTTP/HTTPS service ports to the public Internet.

Specific Symptoms

1. IPv6 anomalies:

   • /56 prefix is assigned
   • Devices receive global IPv6 addresses
   • Yet external network access fails
   • Only the router in bridge mode behind the optical modem retains normal IPv6

2. Tailscale connection anomalies:

   • The source server reports direct connectivity but with excessive latency (~400 ms)
   • Other devices go through relays and obtain lower latency (~80 ms)

ISP Policy Analysis

Telecom carriers in certain regions apply service degradation to inbound-heavy HTTP/HTTPS connections:

1. IPv6 service downgrade

   • Addresses are still assigned
   • Routing tables are missing
   • Effective Internet access is blocked

2. P2P connection throttling

   • Tailscale shows direct connections
   • Actual latency is abnormally high
   • Bandwidth is restricted

Solutions

1. Disable reverse-proxy services:

   • Deactivate Cloudflare/Alibaba Cloud ESA reverse proxies
   • After multiple router reboots, connectivity returns to normal

2. Prevent domain scanning: Avoid these common sub-domains:

   - home.example.com
   - ddns.example.com
   - dev.example.com
   - test.example.com
   

3. Best practices:

   • Use a GUID to generate random sub-domains
   • Refrain from predictable or common sub-domain naming
   • Rotate domains periodically to reduce scanning risk

Some Characteristics of China Telecom IPv6

• Some Characteristics of China Telecom IPv6

• Some Characteristics of China Telecom IPv6

IPv6 has been fully rolled out nationwide; the IPv6 address pool is large enough for each of every individual’s devices to obtain its own IPv6 address.
To actually use IPv6 at home, the entire stack of devices must all support IPv6. Because the rollout has been underway for many years, virtually every device bought after 2016 already supports IPv6.

The full stack includes: metro equipment → community router → home router (ONT/router) → end device (phones, PCs, smart TVs, etc.)

This article does not discuss the standard IPv6 protocol itself; it focuses only on certain characteristics of China Telecom’s IPv6.

Address Allocation

First, the methods of address assignment. IPv6 offers three ways to obtain an address: static assignment, SLAAC, and DHCPv6.
Hubei Telecom uses SLAAC, meaning the IPv6 address is automatically assigned by the device. Because the carrier’s IPv6 pool is enormous, address conflicts are impossible.

Telecom IPv6 addresses are assigned at random and recycled every 24 h. If you need inbound access, you must use a DDNS service.

Firewall

At present it can be observed that common ports such as 80, 139, 445 are blocked—mirroring the carrier’s IPv4 firewall. This is easy to understand: operator-level firewalls do protect ordinary users who lack security awareness. In 2020, China Telecom IPv6 was fully open, but now certain common ports have been blocked.

Port 443 is occasionally accessible within the China Telecom network but blocked for China Mobile and China Unicom. Developers must keep this in mind. A service that works fine in your dev environment—or that your phone on the China Telecom network can reach—may be unreachable from a phone on a different carrier.

Based on simple firewall testing, developers are strongly advised not to trust operator firewalls. Serve your application on a five-digit port.

Furthermore, China Telecom’s firewall does not block port 22, and Windows Remote Desktop port 3389 is likewise open.
Consequently, remote login is possible—introducing obvious risks.

Once attackers obtain the IP or DDNS hostname, they can start targeted attacks; brute-force password cracking can grant control of the device. The domain name can also reveal personal information—name, address, etc.—and attackers may use social-engineering tactics to gather even more clues to speed up their intrusion.

It is recommended to disable password authentication for ssh and rely only on key-based login, or to use a VPN, or to employ a jump host for remote access.

Why we should not think of UDP in terms of TCP

• Why we should not think of UDP in terms of TCP

Why we should not think of UDP in terms of TCP?

Structural Differences

TCP has many concepts: connection establishment, resource usage, data transfer, reliable delivery, retransmission based on cumulative ACK-SACK, timeout retransmission, checksum, flow control, congestion control, MSS, selective acknowledgements, TCP window scale, TCP timestamps, PSH flag, connection termination.

UDP has virtually none of these facilities; it is only slightly more capable than the link layer in distinguishing applications. Because UDP is extremely simple, it is extremely flexible.

If it can happen, it will

Murphy’s law:

If anything can go wrong, it will.

Conventional wisdom suggests that UDP suits games, voice, and video because a few corrupt packets rarely matter. The reason UDP is chosen for these use-cases is not that it is the perfect match, but that there are unsolved problems for TCP that force services to pick the less-featured UDP. Saying “a few corrupt packets do not disturb the service” actually means that TCP worries about packet correctness while UDP does not; UDP cares more about timeliness and continuity. UDP’s defining trait is its indifference to everything TCP considers important—factors that harm real-time performance.

In code, UDP only needs one socket bound to a port to begin sending and receiving. Usually the socket lifetime matches the port lifetime.

Therefore, I can use UDP like this:

1. Send random datagrams to any IP’s any port and see who replies.
2. Alice sends a request from port A to port B of Bob, Bob responds from port C to Alice’s port D.
3. Alice same as above, but Bob asks Charlie to answer from port C to Alice’s port D.
4. Alice sends a request from port A to port B, but spoofs the source address to Charlie’s address; Bob will reply to Charlie.
5. Both sides agree to open ten UDP ports and send as well as receive on each one concurrently.

Of course none of these patterns can exist in TCP, but in UDP, because they are possible, sooner or later someone will adopt them. Expecting UDP to behave like TCP is therefore idealistic; reality cannot be fully enumerated.

UDP datagrams are extremely lightweight and highly flexible; the idea of a “connection” does not exist at the protocol level, so you must invent your own notion of a UDP connection. Different definitions were tried, yet none could always unambiguously describe direction from a single datagram; we must accept ambiguity. After all, no official “UDP connection” standard exists—when parties hold different definitions, mismatched behaviours are inevitable.

UDP from the client’s viewpoint

Voice or video can suffer packet loss, but the loss pattern has very different effects on user experience. For example, losing 30 % of packets evenly or losing 30 % all within half a second produces drastically different experiences; the former is obviously preferable. However, UDP has no built-in flow control to deliberately throttle traffic. Although UDP is often described as “best-effort”, the details of that effort still determine the outcome.

UDP from the provider’s viewpoint

For TCP attacks, the client must invest computational resources to create and maintain connections—attackers thus incur costs. With UDP, the attacker’s overhead is much lower; if the goal is just to burn server bandwidth, UDP is perfect. Suppose the service buys 100 GB of unmetered traffic but only processes 10 MB/s while accepting 1 GB/s—90 % of the arriving traffic is junk, yet it is still billable. Providers should avoid such situations.

UDP from the ISP’s viewpoint

End-to-end communication comprises multiple endpoints and transit paths. We usually focus only on client and server viewpoints, but the ISP’s perspective matters too. Under DDoS, we pay attention to server capacity, ignoring the ISP’s own finite resources. The server may ignore useless requests, yet the ISP has already paid to carry them. When we perform stress tests we often report “packet loss”, overlooking that the number reflects loss along the entire path—not just at the server. ISPs drop packets as well. From the ISP’s view, the service purchased 1 MB/s, but the client send rate is 1 GB/s; they both pay nothing for the wasted bandwidth—the ISP bears the cost. To avoid that, ISPs implement UDP QoS. Compared to TCP’s congestion control, ISPs can just drop UDP. In practice the blunt approach is to block traffic on long-lived UDP ports. Field tests of WeChat calls show that each call uses multiple ports with one UDP port talking to six different UDP ports on the same server—likely a countermeasure to ISP port blocks.

Summary

UDP’s flexibility usually means there are several legitimate methods to reach a goal; as long as the program eventually communicates stably, however bizarre it may appear compared with TCP, it is “the way it is”. We therefore cannot force TCP concepts onto UDP. Even when we invent a new “UDP connection” for product design, we must expect and gracefully accept errors—the ability to tolerate errors is UDP’s core feature, an advantage deliberately chosen by the service, not a flaw we have to live with.

Further reading

• Learning the principles of QoS in 20 000 words
• Transmission Control Protocol
• User Datagram Protocol

Troubleshooting Linux Network Issues

Troubleshooting Tools

How to Improve Network Experience with a Self-Hosted DNS Service

Network Quality vs. Network Experience

Do nothing, and you’ll already enjoy the best network experience.

First, note that “network quality” and “network experience” are two different concepts. Communication is a process involving many devices. The upload/download performance of a single device can be termed network quality, while the end-to-end behavior of the entire communication path is what we call network experience.

Measuring Network Quality

Evaluating network quality usually involves several metrics and methods. Common ones include:

1. Bandwidth – the capacity to transfer data, conventionally expressed in bits-per-second. Higher bandwidth generally indicates better quality.
2. Latency – the time a packet takes to travel from sender to receiver. Lower latency means faster response.
3. Packet-loss rate – the proportion of packets lost en route. A lower rate suggests higher quality.
4. Jitter – variability in packet arrival times. Smaller jitter means a more stable network.
5. Throughput – the actual data volume successfully transported in a given period.
6. Network topology – the physical or logical arrangement of network nodes; good design improves quality.
7. Quality-of-Service (QoS) – techniques such as traffic shaping and priority queues that ensure acceptable service levels.
8. Protocol analysis – examining traffic with tools like Wireshark to diagnose bottlenecks or errors.

Combined, these indicators give a complete picture of network performance and improvement opportunities. Carriers need these details, but ordinary users often need only a decently priced modern router—today’s devices auto-tune most of these knobs.

Measuring Network Experience

The first factor is reachability—being able to connect at all. A DNS service must therefore be:

• Comprehensive: its upstream resolvers should be authoritative and able to resolve the largest possible set of names.
• Accurate: results must be correct and free from hijacking or pollution returning advertisement pages.
• Timely: when an IP changes, the resolver must return the fresh address, not a stale record.

Next comes the network quality of the resolved IP itself.

Because service quality varies strongly with region, servers geographically closer to the client often offer better performance.

Most paid DNS providers support Geo-aware records. For example, Alibaba Cloud allows:

(1) Carrier lines: Unicom, Telecom, Mobile, CERNet, Great Wall Broadband, Cable WAN—down to province level.
(2) Overseas regions: down to continent and country.
(3) Alibaba cloud lines: down to individual regions.
(4) Custom lines: define any IP range for smart resolution.

“(distribution-map-placeholder)”

By resolving IPs based on location, distant users reach nearby servers automatically—boosting experience without them lifting a finger.

In practice, service providers optimize UX based on the client’s real address. For most users, doing nothing gives the best network experience.

Choosing Upstream Resolvers for Self-Hosted DNS

Nearly every Chinese-language guide tells you to pick large authoritative resolvers—Alibaba, Tencent, Cloudflare, Google—because they score high on reachability (comprehensive, accurate, timely). Yet they do not guarantee you the nearest server.

There’s historical context: Chinese ISPs once hijacked DNS plus plaintext HTTP to inject ads. Today, with HTTPS prevalent, this is far less common, though some last-mile ISPs may still try it. Simply switching resolvers to random IPs won’t save you from hijacks directed at UDP 53.

Another user niche cares about content filtering; some providers return bogus IPs for “special” sites. Authoritative resolvers rarely exhibit this behavior.

So three problems arise:

1. IP contamination
2. DNS hijacking
3. Optimal service experience

Authoritative resolvers fix (1); encrypted transports (DoT/DoH/QUIC) mitigate (2).

For (3) you must go back to your carrier’s default DNS. As we said: “Do nothing, and you’ll already enjoy the best network experience.”

But if you’re a perfectionist or a special user, the sections below show how to configure AdGuard Home and Clash to satisfy all three concerns at once.

Authoritative yet “Smart” DNS

AdGuard Home Configuration

AdGuard Home (ADG) is an ad-blocking, privacy-centric DNS server. It supports custom upstream resolvers and custom rules.

ADG’s default mode is load-balancing: you list several upstreams; ADG weights them by historical response speed and chooses the fastest. In simple terms, it will favor the quickest upstream more often.

Pick the third option instead: “Fastest IP address”.

“(ui-screenshot-placeholder)”

Result: ADG tests the IPs returned by each upstream and replies with whichever has the lowest latency. Below are ordinary results for bilibili.com:

“(ordinary-results-screenshot-placeholder)”

Without this option, ADG would hand every IP back to the client: some apps pick the first, others the last, others pick at random—possibly far from optimal.

With “Fastest IP address” enabled:

“(optimized-results-screenshot-placeholder)”

That alone improves network experience.

Why isn’t “Fastest IP address” the default?
Because waiting for all upstream answers means query time equals the slowest upstream. If you mix a 50 ms Ali server with a 500 ms Google one, your upstream delay becomes ~500 ms.

So users must balance quality vs. quantity. I suggest keeping two upstreams only: one authoritative (https://dns.alidns.com/dns-query) plus your local carrier’s DNS.

Carrier DNS IPs differ by city; look yours up here or read them from your router’s status page:

“(router-dns-screenshot-placeholder)”

Clash Configuration

Users with special needs who still want optimal routing can delegate DNS handling to Clash’s dns section.

nameserver-policy lets you assign different domains to different resolvers. Example:

dns:
  default-nameserver:
    - tls://223.5.5.5:853
    - tls://1.12.12.12:853
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://one.one.one.one/dns-query
    - https://dns.google/dns-query
  nameserver-policy:
    "geosite:cn,private,apple":
      - 202.103.24.68 # your local carrier DNS
      - https://dns.alidns.com/dns-query
    "geosite:geolocation-!cn":
      - https://one.one.one.one/dns-query
      - https://dns.google/dns-query

Meaning:

• default-nameserver – used solely to resolve hostnames of DNS services in the nameserver list.
• nameserver – standard resolvers for ordinary queries.
• nameserver-policy – overrides above resolvers for specific groups of domains.

Thanks for Reading

If this post helped you, consider giving it a thumbs-up. Comments and discussion are always welcome!

Bypassing ChatGPT VPN Detection

How to handle the ChatGPT error messages
“Unable to load site”
“Please try again later; if you are using a VPN, try turning it off.”
“Check the status page for information on outages.”

Foreword

ChatGPT is still the best chatbot in terms of user experience, but in mainland China its use is restricted by the network environment, so we need a proxy (literally a “ladder”) to reach it. ChatGPT is, however, quite strict in detecting proxies, and if it finds one it will simply refuse service. This article explains a way around that detection.

Some people suggest switching IPs to evade a block, yet the geolocations we can get from our providers already belong to supported regions, so this is not necessarily the real reason for denial of service.

Others argue that popular shared proxies are too easy to fingerprint and advise buying more expensive “uncrowded” ones, yet this is hardly a solid argument—IPv4 addresses are scarce, so even overseas ISPs often allocate ports via NAT. Blocking one address would hit a huge community, something that a service as widely used as ChatGPT surely would not design for.

For a public service, checking source-IP consistency makes more sense. Paid proxy plans typically impose data or speed limits, so most users adopt split-routing: they proxy only when the destination is firewalled, letting non-filtered traffic travel directly. This choice of paths can result in inconsistent source IPs. For example, Service A needs to talk to Domains X and Y, yet only X is firewalled; the proxy will be used for X but not Y, so A sees the same request coming from two different IPs.

Solving this source-IP inconsistency will bypass ChatGPT’s “ladder” identification.

Proxy rules usually include domain rules, IP rules, and so on.

Remember that the result of a domain resolution varies by region—if you are in place A you get a nearby server, and in place B you may get another. Therefore, DNS selection matters.

DNS Selection

Today there are many DNS protocols; UDP:53 is so outdated and insecure that China lists DNS servers as a top-level requirement for companies. Such rules arose from decades of carriers employing DNS hijacking plus HTTP redirection to insert advertisements, deceiving many non-tech-savvy users and leading to countless complaints. Although today Chrome/Edge automatically upgrade to HTTPS and mark plain HTTP as insecure, many small neighbourhood ISPs and repackaged old Chromium versions persist, so DNS and HTTP hijacking still occur.

Hence we need a safe DNS protocol to avoid hijacking. In my experience Alibaba’s public 223.5.5.5 works well. Of course, when I mention 223.5.5.5 I do not mean plain UDP but DoH or DoT. Configure with tls://223.5.5.5 or https://dns.alidns.com/dns-query.

Alidns rarely gets poisoned—only during certain sensitive periods. You can also use my long-term self-hosted resolver tls://dns.jqknono.com, upstreaming 8.8.8.8 and 1.1.1.1, with cache acceleration.

Domain Rules

The detection page first visited runs probing logic, sending requests to several domains to check the source IP, so domain routing must remain consistent.

Besides its own, ChatGPT relies on third-party domains such as auth0, cloudflare, etc.

Add the following rules by hand:

# openai
- DOMAIN-SUFFIX,chatgpt.com,PROXY
- DOMAIN-SUFFIX,openai.com,PROXY
- DOMAIN-SUFFIX,openai.org,PROXY
- DOMAIN-SUFFIX,auth0.com,PROXY
- DOMAIN-SUFFIX,cloudflare.com,PROXY

How to test domain rules

The domains above may evolve as ChatGPT’s services change; here is how to discover them yourself.

1. Open a private/Incognito window to avoid caches/cookies.
2. Press F12 to open DevTools, switch to the Network tab.
3. Visit chat.openai.com or chatgpt.com.
4. The following screenshot shows the domains used at the time of writing:

Adding just those domains may still be insufficient. Inspect each aborted request: the challenge response’s Content-Security-Policy lists many domains. Add every one to the proxy policy.

# openai
- DOMAIN-SUFFIX,chatgpt.com,PROXY
- DOMAIN-SUFFIX,openai.com,PROXY
- DOMAIN-SUFFIX,openai.org,PROXY
- DOMAIN-SUFFIX,auth0.com,PROXY
- DOMAIN-SUFFIX,cloudflare.com,PROXY
# additional
- DOMAIN-SUFFIX,oaistatic.com,PROXY
- DOMAIN-SUFFIX,oaiusercontent.com,PROXY
- DOMAIN-SUFFIX,intercomcdn.com,PROXY
- DOMAIN-SUFFIX,intercom.io,PROXY
- DOMAIN-SUFFIX,mixpanel.com,PROXY
- DOMAIN-SUFFIX,statsigapi.net,PROXY
- DOMAIN-SUFFIX,featuregates.org,PROXY
- DOMAIN-SUFFIX,stripe.com,PROXY
- DOMAIN-SUFFIX,browser-intake-datadoghq.com,PROXY
- DOMAIN-SUFFIX,sentry.io,PROXY
- DOMAIN-SUFFIX,live.net,PROXY
- DOMAIN-SUFFIX,live.com,PROXY
- DOMAIN-SUFFIX,windows.net,PROXY
- DOMAIN-SUFFIX,onedrive.com,PROXY
- DOMAIN-SUFFIX,microsoft.com,PROXY
- DOMAIN-SUFFIX,azure.com,PROXY
- DOMAIN-SUFFIX,sharepoint.com,PROXY
- DOMAIN-SUFFIX,gstatic.com,PROXY
- DOMAIN-SUFFIX,google.com,PROXY
- DOMAIN-SUFFIX,googleapis.com,PROXY
- DOMAIN-SUFFIX,googleusercontent.com,PROXY

IP Rules

If the site still refuses to load after the steps above, IP-based detection may also be in play. Below are some IPs I intercepted; they may not fit every region, so test on your own.

# openai
- IP-CIDR6,2606:4700:4400::6812:231c/96,PROXY
- IP-CIDR,17.253.84.253/24,PROXY
- IP-CIDR,172.64.152.228/24,PROXY
- IP-CIDR,104.18.35.28/16,PROXY

How to test IP rules

Know your proxy tool. Open its connection log, watch the new connections as you reproduce the steps, then add the IPs you see.

A quick guide:

1. Open a private/Incognito window.
2. Visit chat.openai.com or chatgpt.com.
3. Monitor the new connections in your proxy client and copy their IPs into rules.

Protocol Rules

QUIC is an encrypted UDP protocol, and ChatGPT makes heavy use of QUIC traffic. Therefore both client and server must support UDP forwarding; many do not. Even with support, you must explicitly enable it—some clients default to not proxy UDP traffic. If unsure about UDP, either block QUIC in the proxy client or disable it in the browser; the browser will automatically fall back to HTTP/2 over TCP. QUIC provides smoother performance; feel free to experiment.

The simplest config – whitelist mode

Set direct connections only for Chinese IPs and proxy everything else. This grants reliable ChatGPT access and also covers other foreign services.

The downside is higher data consumption and dependency on your proxy’s quality. If you trust your proxy’s network, give this a shot.

Of course, do remember to enable UDP forwarding.

Chat

• _index

Which Languages Are Best for Multilingual Projects

Below are 15 countries/regions—selected based on population size, economic output, and international influence—together with their language codes (shortcodes) and brief rationales, intended as a reference for multilingual translation:

Notes: Language codes follow the ISO 639-1 (language) + ISO 3166-1 (country) standards, facilitating adaptation to localization tools.
Priority has been given to countries with populations over 100 million, GDPs in the world’s top 20, and those with notable regional influence, balancing international applicability and market value.
For particular domains (e.g., the Latin American market can add es-MX (Mexico), Southeast Asia can add vi-VN (Vietnam)), the list can be further refined as needed.

Third-party Library Pitfalls

• Third-party library pitfalls

Today we talked about a vulnerability in a recently released third-party logging library that can be exploited with minimal effort to execute remote commands. A logging library and remote command execution seem completely unrelated, yet over-engineered third-party libraries are everywhere.

The more code I read, the more I feel that a lot of open-source code is of very poor quality—regardless of how many k-stars it has. Stars represent needs, not engineering skill.

The advantage of open source is that more people contribute, allowing features to grow quickly, bugs to get fixed, and code to be reviewed. But skill levels vary wildly.

Without strong commit constraints, code quality is hard to guarantee.

The more code you add, the larger the attack surface.

Although reinventing the wheel is usually bad, product requirements are like a stroller wheel: a plastic wheel that never breaks. Attaching an airplane tire to it just adds attack surface and maintenance costs. So if all you need is a stroller wheel, don’t over-engineer.

Maintenance is expensive. Third-party libraries require dedicated processes and people to maintain them. Huawei once forked a test framework, and when we upgraded the compiler the test cases failed. Upgrading the test framework clashed with the compiler upgrade, so we burned ridiculous time making further invasive changes. As one of the people involved, I deeply felt the pain of forking third-party libraries. If the modifications were feature-worthy they could be upstreamed, but tailoring them to our own needs through intrusive customization makes future maintenance nearly impossible.

Huawei created a whole series of processes for third-party libraries—one could say the friction was enormous.

The bar is set very high: adding a library requires review by a level-18 expert and approval from a level-20 director. Only longtime, well-known libraries even have a chance.

All third-party libraries live under a thirdparty folder. A full build compares them byte-for-byte with the upstream repo; any invasive change is strictly forbidden.

Dedicated tooling tracks every library’s version, managed by outsourced staff. If a developer wants to upgrade a library, they must submit a formal request—and the director has to sign off.

Getting a director to handle something like that is hard. When a process is deliberately convoluted, its real message is “please don’t do this.”

Approach third-party libraries with skepticism—trust code written by your own team.

Design Specification Template

• Design Specification Template

Detailed Design of XXX System / Sub-system

Revision History

Technical Review Comments

Background

Glossary

• SIP: Session Initiation Protocol
• RTP: Real-time Transport Protocol

Design Objectives

Functional Requirements

Non-Functional Requirements (mandatory)

Environment

Related Software & Hardware (optional)

System Constraints

Estimated Data Scale (mandatory)

Existing Solutions

Design Ideas & Trade-offs

Assumptions & Dependencies / Relationships with Other Systems

System Design

Overview

Architecture Diagram & Explanation

System Flow & Explanation (optional)

Interfaces with External Systems

Global Data-Structure Descriptions

Brief Description of Module XXX1

Functionality of Module XXX1

Interfaces with Other Modules

Brief Description of Module XXX2

Functionality of Module XXX2

Interfaces with Other Modules

Threat Modeling

Upgrade Impact (mandatory)

Risk Assessment & Impact on Other Systems (optional)

Known or Foreseeable Risks

Potential Impact with Other Systems/Modules

Innovation Points (optional)

Attachments & References

Command Line Syntax Conventions

• Command line syntax conventions

References

• https://www.ibm.com/docs/en/iotdm/11.3?topic=interface-command-line-syntax
• https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/command-line-syntax-key
• https://developers.google.com/style/code-syntax
• https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_01
• https://ftpdocs.broadcom.com/cadocs/0/CA%20ARCserve%20%20Backup%20r16-CHS/Bookshelf_Files/HTML/cmndline/cl_cmd_line_syntax_char.htm

e.g.

Meanings of brackets in man pages

• Meanings of brackets in man pages

Meanings of brackets in man pages

In command-line help, different types of brackets generally carry the following meanings:

1. Angle brackets <>:
   • Angle brackets denote required arguments—values you must provide when running the command. They’re typically used to express the core syntax and parameters of a command.
   • Example: command <filename> means you must supply a filename as a required argument, e.g., command file.txt.
2. Square brackets []:
   • Square brackets indicate optional arguments—values you may or may not provide when running the command. They’re commonly used to mark optional parameters and options.
   • Example: command [option] means you can choose to provide an option, e.g., command -v or simply command.
3. Curly braces {}:
   • Curly braces usually represent a set of choices, indicating that you must select one. These are also called “choice parameter groups.”
   • Example: command {option1 | option2 | option3} means you must pick one of the given options, e.g., command option2.
4. Parentheses ():
   • Parentheses are generally used to group arguments, clarifying structure and precedence in a command’s syntax.
   • Example: command (option1 | option2) filename means you must choose either option1 or option2 and supply a filename as an argument, e.g., command option1 file.txt.

These bracket conventions are intended to help users understand command syntax and parameter choices so they can use command-line tools correctly. When reading man pages or help text, paying close attention to the meaning and purpose of each bracket type is crucial—it prevents incorrect commands and achieves the desired results.

Huawei C++ Coding Standards

• Huawei C++ Coding Standards

C++ Language Coding Standards

Purpose

Rules are not perfect; by prohibiting features useful in specific situations, they may impact code implementation. However, the purpose of establishing rules is “to benefit the majority of developers.” If, during team collaboration, a rule is deemed unenforceable, we hope to improve it together.

Before referencing this standard, it is assumed that you already possess the corresponding basic C++ language capabilities; do not rely on this document to learn the C++ language.

1. Understand the C++ language ISO standard;
2. Be familiar with basic C++ language features, including those related to C++ 03/11/14/17;
3. Understand the C++ standard library;

General Principles

Code must, while ensuring functional correctness, meet the feature requirements of readability, maintainability, safety, reliability, testability, efficiency, and portability.

Key Focus Areas

1. Define the C++ coding style, such as naming, formatting, etc.
2. C++ modular design—how to design header files, classes, interfaces, and functions.
3. Best practices for C++ language features, such as constants, type casting, resource management, templates, etc.
4. Modern C++ best practices, including conventions in C++11/14/17 that can improve maintainability and reliability.
5. This standard is primarily applicable to C++17.

Conventions

Rule: A convention that must be followed during programming (must).
Recommendation: A convention that should be followed during programming (should).

This standard applies to common C++ standards; when no specific standard version is noted, it applies to all versions (C++03/11/14/17).

Exceptions

Regardless of ‘Rule’ or ‘Recommendation’, you must understand the reasons behind each item and strive to follow them.
However, there may be exceptions to some rules and recommendations.

If it does not violate the general principles and, after thorough consideration, there are sufficient reasons, it is acceptable to deviate from the conventions in the specification.
Exceptions break code consistency—please avoid them. Exceptions to a ‘Rule’ should be extremely rare.

In the following situations, stylistic consistency should take priority:
When modifying external open-source code or third-party code, follow the existing code style to maintain uniformity.

2 Naming

General Naming

CamelCase
Mixed case letters with words connected. Words are separated by capitalizing the first letter of each word.
Depending on whether the first letter after concatenation is capitalized, it is further divided into UpperCamelCase and lowerCamelCase.

Notes:
The constant in the above table refers to variables at global scope, namespace scope, or static member scope that are basic data types, enums, or string types qualified with const or constexpr; arrays and other types of variables are excluded.
The variable in the above table refers to all variables other than the constant definition above, which should all use the lowerCamelCase style.

File Naming

Rule 2.2.1 C++ implementation files end with .cpp, header files end with .h

We recommend using .h as the header suffix so header files can be directly compatible with both C and C++.
We recommend using .cpp as the implementation file suffix to clearly distinguish C++ code from C code.

Some other suffixes used in the industry:

• Header files: .hh, .hpp, .hxx
• cpp files: .cc, .cxx, .c

If your project team already uses a specific suffix, you can continue using it, but please maintain stylistic consistency.
For this document, we default to .h and .cpp as suffixes.

Rule 2.2.2 C++ file names correspond to the class name

C++ header and cpp file names should correspond to the class names in lowercase with underscores.

If a class is named DatabaseConnection, then the corresponding filenames should be:

• database_connection.h
• database_connection.cpp

File naming for structs, namespaces, enums, etc., follows a similar pattern.

Function Naming

Function names use the UpperCamelCase style, usually a verb or verb-object structure.

class List {
public:
    void AddElement(const Element& element);
    Element GetElement(const unsigned int index) const;
    bool IsEmpty() const;
};

namespace Utils {
    void DeleteUser();
}

Type Naming

Type names use the UpperCamelCase style.
All type names—classes, structs, unions, type aliases (typedef), and enums—use the same convention, e.g.:

// classes, structs and unions
class UrlTable { ...
class UrlTableTester { ...
struct UrlTableProperties { ...
union Packet { ...

// typedefs
typedef std::map<std::string, UrlTableProperties*> PropertiesMap;

// enums
enum UrlTableErrors { ...

For namespaces, UpperCamelCase is recommended:

// namespace
namespace OsUtils {
 
namespace FileUtils {
     
}
 
}

Recommendation 2.4.1 Avoid misusing typedef or #define to alias basic types

Do not redefine basic data types with typedef/#define unless there is a clear necessity.
Prefer using basic types from the <cstdint> header:

Variable Naming

General variables use lowerCamelCase, covering global variables, function parameters, local variables, and member variables.

std::string tableName;  // Good: recommended
std::string tablename;  // Bad: prohibited
std::string path;       // Good: single-word lowercase per lowerCamelCase

Rule 2.5.1 Global variables must have a ‘g_’ prefix; static variables need no special prefix

Global variables should be used sparingly; adding the prefix visually reminds developers to use them carefully.

• Static global variables share the same naming as global variables.
• Function-local static variables share normal local variable naming.
• Class static member variables share normal member variable naming.

int g_activeConnectCount;

void Func()
{
    static int packetCount = 0; 
    ...
}

Rule 2.5.2 Class member variables are named in lowerCamelCase followed by a trailing underscore

class Foo {
private:
    std::string fileName_;   // trailing _ suffix, similar to K&R style
};

For struct/union member variables, use lowerCamelCase without suffix, consistent with local variables.

Macro, Constant, and Enum Naming

Macros and enum values use ALL CAPS, underscore-connected format.
Global-scope or named/anonymous-namespace const constants, as well as class static member constants, use ALL CAPS, underscore-connected; function-local const constants and ordinary const member variables use lowerCamelCase.

#define MAX(a, b)   (((a) < (b)) ? (b) : (a)) // macro naming example only—macro not recommended for such a feature

enum TintColor {    // enum type name in UpperCamelCase, values in ALL CAPS, underscore-connected
    RED,
    DARK_RED,
    GREEN,
    LIGHT_GREEN
};

int Func(...)
{
    const unsigned int bufferSize = 100;    // local constant
    char *p = new char[bufferSize];
    ...
}

namespace Utils {
    const unsigned int DEFAULT_FILE_SIZE_KB = 200;        // global constant
}

3 Format

Line Length

Rule 3.1.1 Do not exceed 120 characters per line

We recommend keeping each line under 120 characters. If 120 characters are exceeded, choose a reasonable wrapping method.

Exceptions:

• Lines containing commands or URLs in comments may remain on one line for copy/paste / grep convenience, even above 120 chars.
• #include statements with long paths may exceed 120 chars but should be avoided when possible.
• Preprocessor error messages may span one line for readability, even above 120 chars.

#ifndef XXX_YYY_ZZZ
#error Header aaaa/bbbb/cccc/abc.h must only be included after xxxx/yyyy/zzzz/xyz.h, because xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
#endif

Indentation

Rule 3.2.1 Use spaces for indentation—4 spaces per level

Only use spaces for indentation (4 spaces per level). Do not use tab characters.
Almost all modern IDEs can be configured to automatically expand tabs to 4 spaces—please configure yours accordingly.

Braces

Rule 3.3.1 Use K&R indentation style

K&R Style
For functions (excluding lambda expressions), place the left brace on a new line at the beginning of the line, alone; for other cases, the left brace should follow statements and stay at the end of the line.
Right braces are always on their own line, unless additional parts of the same statement follow—e.g., while in do-while, else/else-if of an if-statement, comma, or semicolon.

Examples:

struct MyType {     // brace follows statement with one preceding space
    ...
};

int Foo(int a)
{                   // function left brace on a new line, alone
    if (...) {
        ...
    } else {
        ...
    }
}

Reason for recommending this style:

• Code is more compact.
• Continuation improves reading rhythm compared to new-line placement.
• Aligns with later language conventions and industry mainstream practice.
• Modern IDEs provide alignment aids so the end-of-line brace does not hinder scoping comprehension.

For empty function bodies, the braces may be placed on the same line:

class MyClass {
public:
    MyClass() : value_(0) {}
   
private:
    int value_;
};

Function Declarations and Definitions

Rule 3.4.1 Both return type and function name must be on the same line; break and align parameters reasonably when line limit is exceeded

When declaring or defining functions, the return type and function name must appear on the same line; if permitted by the column limit, place parameters on the same line as well—otherwise break parameters onto the next line with proper alignment.
The left parenthesis always stays on the same line as the function name; placing it on its own line is prohibited. The right parenthesis always follows the last parameter.

Examples:

ReturnType FunctionName(ArgType paramName1, ArgType paramName2)   // Good: all on one line
{
    ...
}

ReturnType VeryVeryVeryLongFunctionName(ArgType paramName1,     // line limit exceeded, break
                                        ArgType paramName2,     // Good: align with previous
                                        ArgType paramName3)
{
    ...
}

ReturnType LongFunctionName(ArgType paramName1, ArgType paramName2, // line limit exceeded
    ArgType paramName3, ArgType paramName4, ArgType paramName5)    // Good: 4-space indent after break
{
    ...
}

ReturnType ReallyReallyReallyReallyLongFunctionName(            // will not fit first parameter, break immediately
    ArgType paramName1, ArgType paramName2, ArgType paramName3) // Good: 4-space indent after break
{
    ...
}

Function Calls

Rule 3.5.1 Keep function argument lists on one line. If line limit is exceeded, align parameters correctly when wrapping

Function calls should have their parameter list on one line—if exceeding the line length, break and align parameters accordingly.
Left parenthesis always follows the function name; right parenthesis always follows the last parameter.

Examples:

ReturnType result = FunctionName(paramName1, paramName2);   // Good: single line

ReturnType result = FunctionName(paramName1,
                                 paramName2,                // Good: aligned with param above
                                 paramName3);

ReturnType result = FunctionName(paramName1, paramName2,
    paramName3, paramName4, paramName5);                    // Good: 4-space indent on break

ReturnType result = VeryVeryVeryLongFunctionName(           // cannot fit first param, break immediately
    paramName1, paramName2, paramName3);                    // 4-space indent after break

If parameters are intrinsically related, grouping them for readability may take precedence over strict formatting.

// Good: each line represents a group of related parameters
int result = DealWithStructureLikeParams(left.x, left.y,     // group 1
                                         right.x, right.y);  // group 2

if Statements

Rule 3.6.1 if statements must use braces

We require braces for all if statements—even for single-line conditions.

Rationale:

• Code logic is intuitive and readable.
• Adding new code to an existing conditional is less error-prone.
• Braces protect against macro misbehavior when using functional macros (in case the macro omitted braces).

if (objectIsNotExist) {         // Good: braces for single-line condition
    return CreateNewObject();
}

Rule 3.6.2 Prohibit writing if/else/else if on the same line

Branches in conditional statements must appear on separate lines.

Correct:

if (someConditions) {
    DoSomething();
    ...
} else {  // Good: else on new line
    ...
}

Incorrect:

if (someConditions) { ... } else { ... } // Bad: else same line as if

Loops

Rule 3.7.1 Loop statements must use braces

Similar to conditions, we require braces for all for/while loops—even if the body is empty or contains only one statement.

for (int i = 0; i < someRange; i++) {   // Good: braces used
    DoSomething();
}

while (condition) { }   // Good: empty body with braces

while (condition) {
    continue;           // Good: continue indicates empty logic, still braces
}

Bad examples:

for (int i = 0; i < someRange; i++)
    DoSomething();      // Bad: missing braces

while (condition);      // Bad: semicolon appears part of loop, confusing

switch Statements

Rule 3.8.1 Indent case/default within switch bodies one additional level

Indentation for switch statements:

switch (var) {
    case 0:             // Good: indented
        DoSomething1(); // Good: indented
        break;
    case 1: {           // Good: brace indentation if needed
        DoSomething2();
        break;
    }
    default:
        break;
}

Bad:

switch (var) {
case 0:                 // Bad: case not indented
    DoSomething();
    break;
default:                // Bad: default not indented
    break;
}

Expressions

Recommendation 3.9.1 Consistently break long expressions at operators, operators stranded at EOL

When an expression is too long for one line, break at an appropriate operator. Place the operator at the end-of-line, indicating ‘to be continued’.

Example:
// Assume first line exceeds limit

if ((currentValue > threshold) &&  // Good: logical operator at EOL
    someCondition) {
    DoSomething();
    ...
}

int result = reallyReallyLongVariableName1 +    // Good
             reallyReallyLongVariableName2;

After wrapping, either align appropriately or indent subsequent lines by 4 spaces.

int sum = longVariableName1 + longVariableName2 + longVariableName3 +
    longVariableName4 + longVariableName5 + longVariableName6;        // Good: 4-space indent

int sum = longVariableName1 + longVariableName2 + longVariableName3 +
          longVariableName4 + longVariableName5 + longVariableName6;  // Good: aligned

Variable Assignment

Rule 3.10.1 Multiple variable declarations and initializations are forbidden on the same line

One variable initialization per line improves readability and comprehension.

int maxCount = 10;
bool isCompleted = false;

Bad examples:

int maxCount = 10; bool isCompleted = false; // Bad: multiple initializations must span separate lines
int x, y = 0;  // Bad: multiple declarations must be on separate lines

int pointX;
int pointY;
...
pointX = 1; pointY = 2;  // Bad: multiple assignments placed on same line

Exception: for loop headers, if-with-initializer (C++17), structured binding statements (C++17), etc., may declare and initialize multiple variables; forcing separation would hinder scope correctness and clarity.

Initialization

Includes initialization for structs, unions, and arrays.

Rule 3.11.1 Indent initialization lists when wrapping; align elements properly

When breaking struct/array initializers, each continuation is indented 4 spaces. Choose break and alignment points for readability.

const int rank[] = {
    16, 16, 16, 16, 32, 32, 32, 32,
    64, 64, 64, 64, 32, 32, 32, 32
};

Pointers and References

Recommendation 3.12.1 Place the pointer star ‘*’ adjacent to the variable or type—never add spaces on both sides or omit both

Pointer naming: align ‘*’ to either left (type) or right (variable) but never leave/pad both sides.

int* p = nullptr;  // Good
int *p = nullptr;  // Good

int*p = nullptr;   // Bad
int * p = nullptr; // Bad

Exception when const is involved—’*’ cannot trail the variable, so avoid trailing the type:

const char * const VERSION = "V100";

Recommendation 3.12.2 Place the reference operator ‘&’ adjacent to the variable or type—never pad both sides nor omit both

Reference naming: & aligned either left (type) or right (variable); never pad both sides or omit spacing.

int i = 8;

int& p = i;     // Good
int &p = i;     // Good
int*& rp = pi;  // Good: reference to pointer; *& together after type
int *&rp = pi;  // Good: reference to pointer; *& together after variable
int* &rp = pi;  // Good: pointer followed by reference—* with type, & with variable

int & p = i;    // Bad
int&reeeenamespace= i;  // Bad—illustrates missing space or doubled up spacing issues

Preprocessor Directives

Rule 3.13.1 Place preprocessing ‘#’ at the start of the line; nested preprocessor statements may indent ‘#’ accordingly

Preprocessing directives’ ‘#’ must be placed at the beginning of the line—even if inside function bodies.

Rule 3.13.2 Avoid macros except where necessary

Macros ignore scope, type systems, and many rules and are prone to error. Prefer non-macro approaches, and if macros must be used, ensure unique macro names.
In C++, many macro use cases can be replaced:

• Use const or enum for intuitive constants
• Use namespaces to prevent name conflicts
• Use inline functions to avoid call overhead
• Use template functions for type abstraction

Macros may be used for include guards, conditional compilation, and logging where required.

Rule 3.13.3 Do not use macros to define constants

Macros are simple text substitution completed during pre-processing; typeless, unscoped, and unsafe. Debugging errors display the value, not the macro name.

Rule 3.13.4 Do not use function-like macros

Before defining a function-like macro, consider if a real function can be used. When alternatives exist, favor functions.
Disadvantages of function-like macros:

• Lack type checking vs function calls
• Macro arguments are not evaluated (behaves differently than function calls)
• No scope encapsulation
• Heavily cryptic syntax (macro operator # and eternal parentheses) harms readability
• Extensions needed (e.g., GCC statement expressions) hurt portability
• Compiler sees the macro after pre-processing; multi-line macro expansions collapse into one line, hard to debug or breakpoint
• Repeated expansion of large macros increases code size

Functions do not suffer the above negatives, although worst-case cost is reduced performance via call overhead (or due to micro-architecture optimization hassles).
To mitigate, use inline. Inline functions:

• Perform strict type checking
• Evaluate each argument once
• Expand in place with no call overhead
• May optimize better than macros

For performance-critical production code, prefer inline functions over macros.

Exception:
logging macros may need to retain FILE/LINE of the call site.

Whitespace/Blank Lines

Rule 3.14.1 Horizontal spaces should emphasize keywords and key information, avoid excessive whitespace

Horizontal spaces should highlight keywords and key info; do not pad trailing spaces. General rules:

• Add space after keywords: if, switch, case, do, while, for
• Do not pad inside parentheses both-left-and-right
• Maintain symmetry around braces
• No space after unary operators (& * + - ~ !)
• Add spaces around binary operators (= + - < > * / % | & ^ <= >= == !=)
• Add spaces around ternary operators ( ? : )
• No space between pre/post inc/dec (++, –) and variable
• No space around struct member access (., ->)
• No space before comma, but space after
• No space between <> and type names as in templates or casts
• No space around scope operator ::
• Colon (:) spaced according to context when needed

Typical cases:

void Foo(int b) {  // Good: space before left brace

int i = 0;  // Good: spaces around =; no space before semicolon

int buf[BUF_SIZE] = {0};    // Good: no space after {

Function definition/call examples:

int result = Foo(arg1,arg2);
//                      ^    Bad: comma needs trailing space

int result = Foo( arg1, arg2 );
//               ^        ^     Bad: no space after ( before args; none before )

Pointer/address examples:

x = *p;     // Good: no space between * and p
p = &x;     // Good: no space between & and x
x = r.y;    // Good: no space around .
x = r->y;   // Good: no space around ->

Operators:

x = 0;   // Good: spaces around =
x = -5;  // Good: no space between - and 5
++x;     // Good: no space between ++ and x
x--;

if (x && !y)  // Good: spaces around &&, none between ! and y

v = w * x + y / z;  // Good: Binary operators are surrounded by spaces.
v = w * (x + z);    // Good: Expressions inside parentheses are not padded with spaces.

int a = (x < y) ? x : y;  // Good: Ternary operators require spaces before ? and :.

Loops and conditional statements:

if (condition) {  // Good: A space after if, none inside the parentheses
    ...
} else {           // Good: A space after else
    ...
}

while (condition) {}   // Good: Same rules as if

for (int i = 0; i < someRange; ++i) {  // Good: Space after for, after each semicolon
    ...
}

switch (condition) {  // Good: One space between switch and (
    case 0:     // Good: No space between case label and colon
        ...
        break;
    ...
    default:
        ...
        break;
}

Templates and casts

// Angle brackets (< and >) are never preceded by spaces, nor followed directly by spaces.
vector<string> x;
y = static_cast<char*>(x);

// One space between a type and * is acceptable; keep it consistent.
vector<char *> x;

Scope resolution operator

std::cout;    // Good: No spaces around ::

int MyClass::GetValue() const {}  // Good: No spaces around ::

Colons

// When spaces are required

// Good: Space before colon with class derivation
class Sub : public Base {

};

// Constructor initializer list needs spaces
MyClass::MyClass(int var) : someVar_(var)
{
    DoSomething();
}

// Bit field width also gets a space
struct XX {
    char a : 4;
    char b : 5;
    char c : 4;
};

// When spaces are NOT required

// Good: No space after public:, private:, etc.
class MyClass {
public:
    MyClass(int var);
private:
    int someVar_;
};

// No space after case or default in switch statements
switch (value)
{
    case 1:
        DoSomething();
        break;
    default:
        break;
}

Note: Configure your IDE to strip trailing whitespace.

Advice 3.14.1 Arrange blank lines to keep code compact

Avoid needless blank lines to display more code on screen and improve readability. Observe these guidelines:

• Insert blank lines based on logical sections, not on automatic habits.
• Do not use consecutive blank lines inside functions, type definitions, macros, or initializer lists.
• Never use three or more consecutive blank lines.
• Do not leave blank lines right after a brace that opens a block or right before the closing brace; the only exception is within namespace scopes.

int Foo()
{
    ...
}



int Bar()  // Bad: more than two consecutive blank lines.
{
    ...
}


if (...) {
        // Bad: blank line immediately after opening brace
    ...
        // Bad: blank line immediately before closing brace
}

int Foo(...)
{
        // Bad: blank line at start of function body
    ...
}

Classes

Rule 3.15.1 Order class access specifiers as public:, protected:, private: at the same indentation level as class

class MyClass : public BaseClass {
public:      // Note: no extra indentation
    MyClass();  // standard 4-space indent
    explicit MyClass(int var);
    ~MyClass() {}

    void SomeFunction();
    void SomeFunctionThatDoesNothing()
    {
    }

    void SetVar(int var) { someVar_ = var; }
    int GetVar() const { return someVar_; }

private:
    bool SomeInternalFunction();

    int someVar_;
    int someOtherVar_;
};

Within each section group similar declarations and order them roughly as follows: type aliases (typedef, using, nested structs / classes), constants, factory functions, constructors, assignment operators, destructor, other member functions, data members.

Rule 3.15.2 Constructor initializer lists should fit on one line or be indented four spaces and line-wrapped

// If everything fits on one line:
MyClass::MyClass(int var) : someVar_(var)
{
    DoSomething();
}

// Otherwise, place after the colon and indent four spaces
MyClass::MyClass(int var)
    : someVar_(var), someOtherVar_(var + 1)  // Good: space after comma
{
    DoSomething();
}

// If multiple lines are needed, align each initializer
MyClass::MyClass(int var)
    : someVar_(var),            // indent 4 spaces
      someOtherVar_(var + 1)
{
    DoSomething();
}

4 Comments

Prefer clear architecture and naming; only add comments when necessary to aid understanding.

Keep comments concise, accurate, and non-redundant.
Comments are as important as code.
When you change code, update all relevant comments—leaving old comments is destructive.

Use English for all comments.

Comment style

Both /* */ and // are acceptable.
Choose one consistent style for each comment category (file header, function header, inline, etc.).

Note: samples in this document frequently use trailing // merely for explanation—do not treat it as an endorsed style.

File header

Rule 3.1 File headers must contain a valid license notice

/*

• Copyright (c) 2020 XXX
• Licensed under the Apache License, Version 2.0 (the “License”);
• you may not use this file except in compliance with the License.
• You may obtain a copy of the License at

• http://www.apache.org/licenses/LICENSE-2.0
  

• Unless required by applicable law or agreed to in writing, software
• distributed under the License is distributed on an “AS IS” BASIS,
• WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
• See the License for the specific language governing permissions and
• limitations under the License. */

Function header comments

Rule 4.3.1 Provide headers for public functions

Callers need to know behavior, parameter ranges, return values, side effects, ownership, etc.—and the function signature alone cannot express everything.

Rule 4.3.2 Never leave noisy or empty function headers

Not every function needs a comment.
Only add a header when the signature is insufficient.

Headers appear above the declaration/definition using one of the following styles: With //

// One-line function header
int Func1(void);

// Multi-line function header
// Second line
int Func2(void);

With /* */

/* Single-line function header */
int Func1(void);

/*
 * Alternative single-line style
 */
int Func2(void);

/*
 * Multi-line header
 * Second line
 */
int Func3(void);

Cover: purpose, return value, performance hints, usage notes, memory ownership, re-entrancy etc.

Example:

/*
 * Returns bytes actually written, -1 on failure.
 * Caller owns the buffer buf.
 */
int WriteString(const char *buf, int len);

Bad:

/*
 * Function name: WriteString
 * Purpose: write string
 * Parameters:
 * Return:
 */
int WriteString(const char *buf, int len);

Problems:‐ parameters/return empty, function name redundant, unclear ownership.

Inline code comments

Rule 4.4.1 Place comments directly above or to the right of the code

Rule 4.4.2 Put one space after the comment token; right-side comments need ≥ 1 space

Above code: indent comment same as code.
Pick one consistent style.

With //

// Single-line comment
DoSomething();

// Multi-line
// comment
DoSomething();

With /* */

/* Single-line comment */
DoSomething();

/*
 * Alternative multi-line comment
 * second line
 */
DoSomething();

Right-of-code style: 1–4 spaces between code and token.

int foo = 100;  // Right-side comment
int bar = 200;  /* Right-side comment */

Aligning right-side comments is acceptable when cluster is tall:

const int A_CONST = 100;         /* comments may align */
const int ANOTHER_CONST = 200;   /* keep uniform gap */

If the right-side comment would exceed the line limit, move it to the previous standalone line.

Rule 4.4.3 Delete unused code, do not comment it out

Commented-out code cannot be maintained; resurrecting it later risks bugs.
When you no longer need code, remove it. Recoveries use version control.

This applies to /* */, //, #if 0, #ifdef NEVER_DEFINED, etc.

5 Headers

Responsibilities

Headers list a module’s public interface; design is reflected mostly here.
Keep implementation out of headers (inline functions are OK).
Headers should be single-minded; complexity and excessive dependencies hurt compile time.

Advice 5.1.1 Every .cpp file should have a matching .h file for the interface it provides

A .h file declares what the .cpp decides to expose.
If a .cpp publishes nothing to other TUs, it shouldn’t exist—except: program entry point, test code, or DLL edge cases.

Example:

// Foo.h
#ifndef FOO_H
#define FOO_H

class Foo {
public:
    Foo();
    void Fun();

private:
    int value_;
};

#endif

// Foo.cpp
#include "Foo.h"

namespace { // Good: internal helper declared in .cpp, hidden by unnamed namespace or static
    void Bar() {
    }
}

...

void Foo::Fun()
{
    Bar();
}

Header dependencies

Rule 5.2.1 Forbid circular #includes

a.h → b.h → c.h → a.h causes full rebuild on any change.
Refactor architecture to break cycles.

Rule 5.2.2 Every header must have an include guard #define

Do not use #pragma once.

Guidelines:

1. Use a unique macro per file.
2. No code/comments except the header license between #ifndef/#define and the matching #endif.

Example: For timer/include/timer.h:

#ifndef TIMER_INCLUDE_TIMER_H
#define TIMER_INCLUDE_TIMER_H
...
#endif

Rule 5.2.3 Forbid extern declarations of external functions/variables

Always #include the proper header instead of duplicating signatures with extern.
Inconsistencies may appear when the real signature changes; also encourages architectural decay.

Bad: // a.cpp

extern int Fun();   // Bad

void Bar()
{
    int i = Fun();
    ...
}

// b.cpp

int Fun() { ... }

Good: // a.cpp

#include "b.h"   // Good
...

// b.h

int Fun();

// b.cpp

int Fun() { ... }

Exception: testing private members, stubs, or patches may use extern when the header itself cannot be augmented.

Rule 5.2.4 Do not #include inside extern “C”

Such includes may nest extern “C” blocks, and some compilers have limited nesting.
Likewise, C/C++ inter-op headers may silently change linkage specifiers.

Example—files a.h / b.h:

// a.h

...
#ifdef __cplusplus
void Foo(int);
#define A(value) Foo(value)
#else
void A(int)
#endif

// b.h

#ifdef __cplusplus
extern "C" {
#endif
#include "a.h"
void B();
#ifdef __cplusplus
}
#endif

After preprocessing b.h in C++:

extern "C" {
    void Foo(int);
    void B();
}

Foo now gets C linkage although author wanted C++ linkage.

Exception: including a pure C header lacking extern "C" inside extern "C" is acceptable when non-intrusive.

Advice 5.2.1 Prefer #include over forward declarations

Forward declaration quick wins:

1. Saves compile time by reducing header bloat.
2. Breaks needless rebuilds on unrelated header edits.

Drawbacks:

1. Hides real dependencies—changes in the header may not trigger recompilation.
2. Subsequent library changes can break your declaration.
3. Forward declaring std:: names is undefined by C++11.
4. Many declarations are longer than a single #include.
5. Refactoring code just to support forward declaration often hurts performance (pointer members) and clarity.
6. It is hard to decide when it is truly safe.

Hence, prefer #include to keep dependencies explicit.

6 Scope

Namespaces

Advice 6.1.1 Use anonymous namespaces or static to hide file-local symbols

In C++03 static globals/funcs are deprecated, so unnamed namespaces are preferred.

Reasons:

1. static already means too many things.
2. namespace can also encapture types.
3. Encourage uniform namespace usage.
4. static functions cannot instantiate templates—namespaces can.

Never use anonymous namespace or static in a .h file.

// Foo.cpp
namespace {
    const int MAX_COUNT = 20;
    void InternalFun();
}

void Foo::Fun()
{
    int i = MAX_COUNT;
    InternalFun();
}

Rule 6.1.1 Never use using namespace in headers or before #includes

Doing so pollutes every translation unit that includes it.
Example:

// a.h

namespace NamespaceA {
    int Fun(int);
}

// b.h

namespace NamespaceB {
    int Fun(int);
}

using namespace NamespaceB;  // Bad

// a.cpp

#include "a.h"
using namespace NamespaceA;
#include "b.h"         // ambiguity: NamespaceA::Fun vs NamespaceB::Fun

Allowed: bringing in single symbols or aliases inside a custom module namespace in headers:

// foo.h

#include <fancy/string>
using fancy::string;                        // Bad in global namespace
namespace Foo {
    using fancy::string;                    // Good
    using MyVector = fancy::vector<int>;    // C++11 type alias OK
}

Global and static member functions

Advice 6.2.1 Prefer namespaces for free functions; use static members only when tightly coupled to a class

Namespace usage avoids global namespace pollution. Only when a free function is intrinsically related to a specific class should it live as a static member.

Helper logic needed only by a single .cpp belongs in an anonymous namespace.

namespace MyNamespace {
    int Add(int a, int b);
}

class File {
public:
    static File CreateTempFile(const std::string& fileName);
};

Global and static member constants

Advice 6.3.1 Use namespaces to hold constants; use static members only when tied to a class

Namespaces guard against global namespace clutter. Only when the constant is logically owned by a specific class should it be a static member.

Implementation-only constants belong in an anonymous namespace.

namespace MyNamespace {
    const int MAX_SIZE = 100;
}

class File {
public:
    static const std::string SEPARATOR;
};

Global variables

Advice 6.4.1 Minimize global variables; use a singleton instead

Mutable globals create tight, invisible coupling across TUs:

int g_counter = 0;

// a.cpp
g_counter++;

// b.cpp
g_counter++;

// c.cpp
cout << g_counter << endl;

Singleton pattern (global unique object):

class Counter {
public:
    static Counter& GetInstance()
    {
        static Counter counter;
        return counter;
    }

    void Increase()   { value_++; }
    void Print() const { std::cout << value_ << std::endl; }

private:
    Counter() : value_(0) {}
    int value_;
};

// a.cpp
Counter::GetInstance().Increase();

// b.cpp
Counter::GetInstance().Increase();

// c.cpp
Counter::GetInstance().Print();

This keeps state shared globally but with better encapsulation.

Exception: if the variable is module-local (each DLL/so or executable instance carries its own), you cannot use a singleton.

7 Classes

Constructors, copy, move, assignment, and destructors

These special members manage object lifetime:

• Constructor: X()
• Copy constructor: X(const X&)
• Copy assignment operator: operator=(const X&)
• Move constructor: X(X&&) available since C++11
• Move assignment operator: operator=(X&&) available since C++11
• Destructor: ~X()

Rule 7.1.1 All member variables of a class must be explicitly initialized

Rationale: If a class has member variables, does not define any constructors, and lacks a default constructor, the compiler will implicitly generate one, but that generated constructor will not initialize the member variables, leaving the object in an indeterminate state.

Exceptions:

• If the member variable has a default constructor, explicit initialization is not required.

Example: The following code lacks a constructor, so the private data members are uninitialized:

class Message {
public:
    void ProcessOutMsg()
    {
        //…
    }

private:
    unsigned int msgID_;
    unsigned int msgLength_;
    unsigned char* msgBuffer_;
    std::string someIdentifier_;
};

Message message;   // message members are not initialized
message.ProcessOutMsg();   // subsequent use is dangerous

// Therefore, providing a default constructor is necessary, as follows:
class Message {
public:
    Message() : msgID_(0), msgLength_(0), msgBuffer_(nullptr)
    {
    }

    void ProcessOutMsg()
    {
        // …
    }

private:
    unsigned int msgID_;
    unsigned int msgLength_;
    unsigned char* msgBuffer_;
    std::string someIdentifier_; // has a default constructor, no explicit initialization needed
};

Advice 7.1.1 Prefer in-class member initialization (C++11) and constructor initializer lists

Rationale: C++11 in-class initialization makes the default member value obvious at a glance and should be preferred. If initialization depends on constructor parameters or C++11 is unavailable, prefer the initializer list. Compared with assigning inside the constructor body, the initializer list is more concise, performs better, and can initialize const members and references.

class Message {
public:
    Message() : msgLength_(0)  // Good: prefer initializer list
    {
        msgBuffer_ = nullptr;  // Bad: avoid assignment in constructor body
    }
   
private:
    unsigned int msgID_{0};  // Good: use C++11 in-class initialization
    unsigned int msgLength_;
    unsigned char* msgBuffer_;
};

Rule 7.1.2 Declare single-argument constructors explicit to prevent implicit conversions

Rationale: A single-argument constructor not declared explicit acts as an implicit conversion function.
Example:

class Foo {
public:
    explicit Foo(const string& name): name_(name)
    {
    }
private:
    string name_;
};


void ProcessFoo(const Foo& foo){}

int main(void)
{
    std::string test = "test";
    ProcessFoo(test);  // compile fails
    return 0;
}

Compilation fails because ProcessFoo expects a Foo, but a std::string is supplied.

If explicit were removed, the std::string would implicitly convert into a temporary Foo object. Such silent conversions are confusing and may hide bugs. Hence single-argument constructors must be declared explicit.

Rule 7.1.3 Explicitly prohibit copy/move constructs/assignment when not needed

Rationale: Unless the user defines them, the compiler will generate copy constructor, copy assignment operator, move constructor and move assignment operator (move semantics are C++11+).
If the class should not support copying/moving, forbid them explicitly:

1. Make the copy/move ctor or assignment operator private and leave it undefined:

class Foo {
private:
    Foo(const Foo&);
    Foo& operator=(const Foo&);
};

2. Use = delete from C++11, see the Modern C++ section.

3. Prefer inheriting from NoCopyable, NoMovable; disallow macros such as DISALLOW_COPY_AND_MOVE, DISALLOW_COPY, DISALLOW_MOVE.

class Foo : public NoCopyable, public NoMovable {
};

Implementation of NoCopyable and NoMovable:

class NoCopyable {
public:
    NoCopyable() = default;
    NoCopyable(const NoCopyable&) = delete;
    NoCopyable& operator = (NoCopyable&) = delete;
};

class NoMovable {
public:
    NoMovable() = default;
    NoMovable(NoMovable&&) noexcept = delete;
    NoMovable& operator = (NoMovable&&) noexcept = delete;
};

Rule 7.1.4 Provide or prohibit both copy constructor and copy assignment together

Since both operations have copy semantics, allow or forbid them in pairs.

// Both provided
class Foo {
public:
    ...
    Foo(const Foo&);
    Foo& operator=(const Foo&);
    ...
};

// Both defaulted (C++11)
class Foo {
public:
    Foo(const Foo&) = default;
    Foo& operator=(const Foo&) = default;
};

// Both prohibited; in C++11 use `delete`
class Foo {
private:
    Foo(const Foo&);
    Foo& operator=(const Foo&);
};

Rule 7.1.5 Provide or prohibit both move constructor and move assignment together

Move semantics were added in C++11. If a class needs to support moving, both move constructor and move assignment must be present or both deleted.

// Both provided
class Foo {
public:
    ...
    Foo(Foo&&);
    Foo& operator=(Foo&&);
    ...
};

// Both defaulted
class Foo {
public:
    Foo(Foo&&) = default;
    Foo& operator=(Foo&&) = default;
};

// Both deleted
class Foo {
public:
    Foo(Foo&&) = delete;
    Foo& operator=(Foo&&) = delete;
};

Rule 7.1.6 Never call virtual functions in constructors or destructors

Rationale: Calling a virtual function on the object under construction/destruction prevents the intended polymorphic behavior.
In C++, a base class is only building one sub-object at a time.

Example:

class Base {                      
public:               
    Base();
    virtual void Log() = 0;    // Derived classes use different log files
};

Base::Base()         // base constructor
{
    Log();           // virtual call inside ctor
}                                                 

class Sub : public Base {      
public:
    virtual void Log();         
};

When executing Sub sub;, Sub’s ctor runs first but calls Base() first; during Base(), the virtual call to Log binds to Base::Log, not Sub::Log. The same applies in destructors.

Rule 7.1.7 Copy/move constructs/assignment of polymorphic bases must be non-public or deleted

Assigning a derived object to a base object causes slicing: only the base part is copied/moved, breaking polymorphism.
Negative Example:

class Base {                      
public:               
    Base() = default;
    virtual ~Base() = default;
    ...
    virtual void Fun() { std::cout << "Base" << std::endl;}
};

class Derived : public Base {
    ...
    void Fun() override { std::cout << "Derived" << std::endl; }
};

void Foo(const Base &base)
{
    Base other = base; // slicing occurs
    other.Fun(); // calls Base::Fun
}

Derived d;
Foo(d); // derived passed in

Declare copy/move operations delete or private so the compiler rejects such assignments.

Inheritance

Rule 7.2.1 Base class destructors must be virtual; classes not intended for inheritance should be marked final

Rationale: A base destructor must be virtual to ensure derived destructors run when the object is deleted via a base pointer.

Example: A base destructor missing virtual causes memory leaks.

class Base {
public:
    virtual std::string getVersion() = 0;
   
    ~Base()
    {
        std::cout << "~Base" << std::endl;
    }
};

class Sub : public Base {
public:
    Sub() : numbers_(nullptr)
    { 
    }
   
    ~Sub()
    {
        delete[] numbers_;
        std::cout << "~Sub" << std::endl;
    }
   
    int Init()
    {
        const size_t numberCount = 100;
        numbers_ = new (std::nothrow) int[numberCount];
        if (numbers_ == nullptr) {
            return -1;
        }
       
        ...
    }

    std::string getVersion()
    {
        return std::string("hello!");
    }
private:
    int* numbers_;
};

int main(int argc, char* args[])
{
    Base* b = new Sub();

    delete b;
    return 0;
}

Because Base::~Base is not virtual, only its destructor is invoked; Sub::~Sub is skipped and numbers_ leaks.
Exceptions: Marker classes like NoCopyable, NoMovable need neither virtual destructors nor final.

Rule 7.2.2 Virtual functions must not have default arguments

Rationale: In C++, virtual dispatch happens at runtime but default arguments are bound at compile time. The selected function body is from the derived class while its default parameter values come from the base, causing surprising behavior.

Example: the program emits “Base!” instead of the expected “Sub!”

class Base {
public:
    virtual void Display(const std::string& text = "Base!")
    {
        std::cout << text << std::endl;
    }
   
    virtual ~Base(){}
};

class Sub : public Base {
public:
    virtual void Display(const std::string& text  = "Sub!")
    {
        std::cout << text << std::endl;
    }
   
    virtual ~Sub(){}
};

int main()
{
    Base* base = new Sub();
    Sub* sub = new Sub();
  
    ...
   
    base->Display();  // prints: Base!
    sub->Display();   // prints: Sub!
   
    delete base;
    delete sub;
    return 0;
};

Rule 7.2.3 Do not override an inherited non-virtual function

Non-virtual functions are bound statically; only virtual functions provide dynamic dispatch.

Example:

class Base {
public:
    void Fun();
};

class Sub : public Base {
public:
    void Fun();
};

Sub* sub = new Sub();                    
Base* base = sub;

sub->Fun();    // calls Sub::Fun               
base->Fun();   // calls Base::Fun
//...

Multiple Inheritance

Real-world use of multiple inheritance in our code base is rare because it brings several typical problems:

1. The diamond inheritance issue causes data duplication and name ambiguity; C++ introduces virtual inheritance to address it.
2. Even without diamond inheritance, name clashes between different bases can create ambiguity.
3. When a subclass needs to extend/override methods in multiple bases, its responsibilities become unclear, leading to confusing semantics.
4. Inheritance is white-box reuse: subclasses have access to parents’ protected members, creating stronger coupling. Multiple inheritance compounds the coupling.

Benefits:
Multiple inheritance offers a simpler way to assemble interfaces and behaviors.

Hence multiple inheritance is allowed only in the following cases.

Advice 7.3.1 Use multiple inheritance for interface segregation and multi-role composition

If a class must implement several unrelated interfaces, inherit from separate base classes that represent those roles—similar to Scala traits.

class Role1 {};
class Role2 {};
class Role3 {};

class Object1 : public Role1, public Role2 {
    // ...
};

class Object2 : public Role2, public Role3 {
    // ...
};

The C++ standard library also demonstrates this pattern:

class basic_istream {};
class basic_ostream {};

class basic_iostream : public basic_istream, public basic_ostream {
 
};

Overloading

Overload operators only with good reason and without altering their intuitive semantics; e.g., never use ‘+’ for subtraction.
Operator overloading makes code intuitive, but also has drawbacks:

• It can mislead readers into assuming built-in efficiency and overlook potential slowdowns;
• Debugging is harder—finding a function name is easier than locating operator usage.
• Non-intuitive behaviour (e.g., ‘+’ subtracting) obfuscates code.
• Implicit conversions triggered by assignment operator overloads can hide deep bugs. Prefer functions like Equals(), CopyFrom() instead of overloading ==, =.

8 Functions

Function Design

Rule 8.1.1 Keep functions short; no more than 50 non-blank non-comment lines

A function should fit on one screen (≤ 50 lines), do one thing, and do it well.
Long functions often indicate mixed concerns, excessive complexity, or missing abstractions.

Exceptions: Algorithmic routines that are inherently cohesive and complete might exceed 50 lines.

Even if the current version works well, future changes may introduce subtle bugs. Splitting into smaller, focused functions eases readability and maintenance.

Inline Functions

Advice 8.2.1 Inline functions should be no more than 10 lines (non-blank non-comment)

Inline functions retain the usual semantics; they just expand in place. Ordinary functions incur call/return overhead; inline functions substitute the body directly.

Inlining only makes sense for very small functions (1–10 lines). For large functions the call-cost is negligible, and compilers usually fall back to normal calls.
Complex control flow (loops, switch, try-catch) normally precludes inlining.

Virtual functions and recursive functions cannot be inlined.

Function Parameters

Advice 8.3.1 Prefer references over pointers for parameters

References are safer: they cannot be null and cannot be reseated after binding; no null pointer checks required.
On legacy platforms follow existing conventions.
Use const to enforce immutability and document the intent, enhancing readability.

Exception: when passing run-time sized arrays, pointers may be used.

Advice 8.3.2 Use strong typing; avoid void*

C/C++ is strongly typed; keep the style consistent. Strong type checking allows the compiler to detect mismatches early.

Using strong types prevents defects. Watch the poorly typed FooListAddNode below:

struct FooNode {
    struct List link;
    int foo;
};

struct BarNode {
    struct List link;
    int bar;
}

void FooListAddNode(void *node) // Bad: using `void *`
{
    FooNode *foo = (FooNode *)node;
    ListAppend(&g_FooList, &foo->link);
}

void MakeTheList()
{
    FooNode *foo = nullptr;
    BarNode *bar = nullptr;
    ...

    FooListAddNode(bar);        // Wrong: meant `foo`, compiles anyway
}

1. Use template functions for variant parameter types.
2. Prefer polymorphic base-class pointers/ references.

Advice 8.3.3 Functions shall have no more than 5 parameters

Too many parameters increase coupling to callers and complicate testing.

If you exceed this:

• Consider splitting the function.
• Group related parameters into a single struct.

9 Additional C++ Features

Constants and Initialization

Immutable values are easier to understand, trace and analyze; default to const for any definition.

Rule 9.1.1 Do not use macros to define constants

Macros perform simple textual substitution at preprocessing time; error traces and debuggers show raw values instead of names.
Macros lack type checking and scope.

#define MAX_MSISDN_LEN 20    // bad

// use C++ const
const int MAX_MSISDN_LEN = 20; // good

// for C++11+, prefer constexpr
constexpr int MAX_MSISDN_LEN = 20;

Advice 9.1.1 Group related integer constants using enums

Enums are safer than #define or const int; the compiler validates values.

// good:
enum Week {
    SUNDAY,
    MONDAY,
    TUESDAY,
    WEDNESDAY,
    THURSDAY,
    FRIDAY,
    SATURDAY
};

enum Color {
    RED,
    BLACK,
    BLUE
};

void ColorizeCalendar(Week today, Color color);

ColorizeCalendar(BLUE, SUNDAY); // compile-time error: type mismatch

// poor:
const int SUNDAY = 0;
const int MONDAY = 1;

const int BLACK  = 0;
const int BLUE   = 1;

bool ColorizeCalendar(int today, int color);
ColorizeCalendar(BLUE, SUNDAY); // compiles fine

When enum values map to specific constants, assign them explicitly; otherwise omit assignments to avoid redundancy.

// good: device types per protocol S
enum DeviceType {
    DEV_UNKNOWN = -1,
    DEV_DSMP = 0,
    DEV_ISMG = 1,
    DEV_WAPPORTAL = 2
};

Internal enums used only for categorization should not have explicit values.

// good: session states
enum SessionState {
    INIT,
    CLOSED,
    WAITING_FOR_RESPONSE
};

Avoid duplicate values; if unavoidable, qualify them:

enum RTCPType {
    RTCP_SR = 200,
    RTCP_MIN_TYPE = RTCP_SR,       
    RTCP_RR    = 201,
    RTCP_SDES  = 202,
    RTCP_BYE   = 203,
    RTCP_APP   = 204,
    RTCP_RTPFB = 205,
    RTCP_PSFB  = 206,
    RTCP_XR  = 207,
    RTCP_RSI = 208,
    RTCP_PUBPORTS = 209,
    RTCP_MAX_TYPE = RTCP_PUBPORTS 
};

Rule 9.1.2 Forbid magic numbers

“Magic numbers” are literals whose meaning is opaque or unclear.
Clarity is contextual: type = 12 is unclear, whereas monthsCount = yearsCount * 12 is understandable.
Even 0 can be cryptic, e.g., status = 0.

Solution:
Comment locally used literals, or create named const for widely used ones.

Prohibited practices:

• Names just map a macro to the literal, e.g., const int ZERO = 0
• Names hard-code limits, e.g., const int XX_TIMER_INTERVAL_300MS = 300; use XX_TIMER_INTERVAL_MS.

Rule 9.1.3 Each constant shall have a single responsibility

A constant must express only one concept; avoid reuse for unrelated purposes.

// good: for two protocols that both allow 20-digit MSISDNs
const unsigned int A_MAX_MSISDN_LEN = 20;
const unsigned int B_MAX_MSISDN_LEN = 20;

// or use distinct namespaces
namespace Namespace1 {
    const unsigned int MAX_MSISDN_LEN = 20;
}

namespace Namespace2 {
    const unsigned int MAX_MSISDN_LEN = 20;
}

Rule 9.1.4 Do not use memcpy_s, memset_s to initialize non-POD objects

POD (“Plain Old Data”) includes primitive types, aggregates, etc., without non-trivial default constructors, virtual functions, or base classes.
Non-POD objects (e.g., classes with virtual functions) have uncertain layouts defined by the ABI; misusing memory routines leads to undefined behavior. Even for aggregates, raw memory manipulation violates information hiding and should be avoided.

See the appendix for detailed POD specifications.

Advice 9.1.2 Declare variables at point of first use and initialize them

Using un-initialized variables is a common bug. Defining variables as late as possible and initializing immediately avoids such errors.

Declaring all variables up front leads to:

• Poor readability and maintenance: definition sites are far from usage sites.
• Variables are hard to initialize appropriately: at the beginning of a function, we often lack enough information to initialize them, so we initialize them with some empty default (e.g., zero). That is usually a waste and can also lead to errors if the variable is used before it is assigned a valid value.

Following the principle of minimizing variable scope and declaring variables as close as possible to their first use makes code easier to read and clarifies the type and initial value of every variable. In particular, initialization should be used instead of declaration followed by assignment.

// Bad: declaration and initialization are separated
string name;        // default-constructed at declaration
name = "zhangsan";  // assignment operator called; definition far from declaration, harder to understand

// Good: declaration and initialization are combined, easier to understand
string name("zhangsan");  // constructor called directly

Expressions

Rule 9.2.1 Do not reference a variable again inside the same expression that increments or decrements it

C++ makes no guarantee about the order of evaluation when a variable that undergoes pre/post increment or decrement is referenced again within the same expression. Different compilers—or even different versions of the same compiler—may behave differently.
For portable code, never rely on such unspecified sequencing.

Notice that adding parentheses does not solve the problem, because this is a sequencing issue, not a precedence issue.

Example:

x = b[i] + i++; // Bad: the order of evaluating b[i] and i++ is unspecified.

Write the increment/decrement on its own line:

x = b[i] + i;
i++;            // Good: on its own line

Function arguments

Func(i++, i);   // Bad: cannot tell whether the increment has happened when passing the second argument

Correct:

i++;            // Good: on its own line
x = Func(i, i);

Rule 9.2.2 Provide a default branch in every switch statement

In most cases, a switch statement must contain a default branch so that unlisted cases have well-defined behavior.

Exception: If the control variable is of an enum type and all enumerators are covered by explicit case labels, a default branch is superfluous.
Modern compilers issue a warning when an enumerator in an enum is missing from the switch.

enum Color {
    RED = 0,
    BLUE
};

// Because the switch variable is an enum and all enumerators are covered, we can omit default
switch (color) {
    case RED:
        DoRedThing();
        break;
    case BLUE:
        DoBlueThing();
        ...
        break;
}